Subscriptions

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Overview

Subscriptions allow external systems to receive automatic notifications when certain resources in the API change.
By registering a subscription, your system can stay synchronized without the need for polling.

Each subscription represents a webhook configuration tied to one or more event types (e.g. created, updated, deleted) for a given resource.

Endpoints

List Subscriptions

GET /api/v1/resources/subscriptions

Returns all active subscriptions for the current authenticated user or consumer.

Response Example

{
  "count": 1,
  "subscriptions": [
    {
      "id": "f2b8e9d3-31c5-4a77-b814-f447bbab9fd2",
      "resource_type": "subscription",
      "webhook_url": "https://example.com/webhooks/receive",
      "event_type": ["created", "updated"],
      "status": "active",
      "start_date": "2024-01-01T00:00:00Z",
      "end_date": null
    }
  ]
}

Create Subscription

POST /api/v1/resources/subscriptions

Registers a new webhook endpoint for receiving events.

Request Body

{
  "resource_type": "subscription",
  "webhook_url": "https://example.com/webhooks/receive",
  "event_type": ["created", "updated"]
}

Response (201)

{
  "id": "f2b8e9d3-31c5-4a77-b814-f447bbab9fd2",
  "resource_type": "subscription",
  "webhook_url": "https://example.com/webhooks/receive",
  "event_type": ["created", "updated"],
  "status": "active",
  "signing_secret": "8d4e4a7f24c...c9820b"
}

Get Subscription

GET /api/v1/resources/subscriptions/{subscription}

Retrieves a single subscription by its unique ID (UUID).

Test Subscription

POST /api/v1/resources/subscriptions/{subscription}/test

Triggers a test webhook call to the configured webhook_url.
The response will be 202 Accepted if the test is queued successfully.

Delete Subscription

DELETE /api/v1/resources/subscriptions/{subscription}

Cancels an existing subscription and stops event delivery.

Webhook Event Delivery

When an event occurs (e.g. a product is created or updated), the system will send an HTTP POST request to your webhook_url.

Example webhook payload

{
  "event_type": "updated",
  "resource": "product",
  "resource_id": "12345",
  "timestamp": "2025-10-21T12:00:00Z",
  "data": {
    "id": "12345",
    "name": "Updated Product Name"
  },
  "signature": "sha256=ab0b71c8..."
}

Each payload includes a signature generated using the signing_secret issued at subscription creation.
Use this signature to verify authenticity before processing the data.

Security & Verification

• All webhook requests are signed using HMAC-SHA256 and the signing_secret.
• Webhook URLs must use HTTPS.
• Retry behavior may be implemented by the client; failed deliveries should be logged and retried as needed.

Typical Flow

1. Create a subscription with your webhook URL.
2. Verify incoming webhook requests using the provided signing secret.
3. Receive notifications automatically whenever a subscribed event occurs.
4. Test the webhook endpoint with /test.
5. Delete the subscription when no longer needed.

Best Practices

• Respond with 2xx to confirm successful webhook receipt.
• Use idempotency when processing duplicate events.
• Store the subscription.id to manage or revoke later.
• Rotate signing_secret periodically for security.