REST API / Webhooks

Webhooks

Supported event types

order.createdorder.status_updatedorder.items_cancelledorder.shippedorder.deliveredorder.cancelledorder.payment_releasedorder.refundedorder.refund_failedorder.dispute_openedorder.dispute_resolvedreturn.createdreturn.status_updatedproduct.updatedproduct.archivedcatalog.import_completedstock.lowstock.outaccount.status_changed

See the Webhook Events guide for payload shapes and signature verification.

GET/v1/webhooks

List webhooks

Returns all webhook endpoints registered on your account.

Response

200 OK

{
  "data": [
    {
      "id": "wh-001",
      "name": "My store webhooks",
      "url": "https://mystore.com/hooks/feedapi",
      "events": [
        "order.created",
        "order.shipped",
        "stock.low"
      ],
      "is_active": true,
      "created_at": "2025-06-01T10:00:00.000Z",
      "updated_at": "2025-06-20T08:00:00.000Z"
    }
  ]
}

POST/v1/webhooks

Create webhook

Registers a new webhook endpoint. The `secret` is returned only once — store it securely to verify signatures.

Request body

application/json

{
  "name": "My store webhooks",
  "url": "https://mystore.com/hooks/feedapi",
  "events": [
    "order.created",
    "order.shipped",
    "product.updated"
  ]
}

Response

200 OK

{
  "data": {
    "id": "wh-001",
    "name": "My store webhooks",
    "url": "https://mystore.com/hooks/feedapi",
    "events": [
      "order.created",
      "order.shipped",
      "product.updated"
    ],
    "is_active": true,
    "created_at": "2025-06-24T10:00:00.000Z"
  }
}

Error responses

409

{
  "error": {
    "code": "CONFLICT",
    "message": "You already have a webhook endpoint.",
    "status": 409
  }
}

PATCH/v1/webhooks/{id}

Update webhook

Updates one or more fields on a webhook. All fields are optional — only send what you want to change.

Path parameters

iduuid

required

Webhook UUID

Request body

application/json

{
  "events": [
    "order.created",
    "order.shipped",
    "order.delivered"
  ],
  "is_active": true
}

Response

200 OK

{
  "data": {
    "id": "wh-001",
    "name": "My store webhooks",
    "url": "https://mystore.com/hooks/feedapi",
    "events": [
      "order.created",
      "order.shipped",
      "order.delivered"
    ],
    "is_active": true,
    "updated_at": "2025-06-24T12:00:00.000Z"
  }
}

DELETE/v1/webhooks/{id}

Delete webhook

Permanently deletes a webhook endpoint. Returns HTTP 204 with no body on success.

Path parameters

iduuid

required

Webhook UUID

POST/v1/webhooks/{id}/rotate-secret

Rotate signing secret

Generates a new HMAC signing secret for this endpoint and invalidates the old one immediately. The new `secret` is returned only once — store it securely. Use this if a secret is ever leaked, instead of deleting and recreating the endpoint (which would lose its delivery history).

Path parameters

iduuid

required

Webhook UUID

Response

200 OK

{
  "data": {
    "id": "wh-001",
    "secret": "whsec_8f2a1c9e4b7d3f6058a1c9e4b7d3f605..."
  }
}

Error responses

404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Webhook not found",
    "status": 404
  }
}

GET/v1/webhooks/{id}/deliveries

Delivery logs

Returns the last 20 delivery attempts for a webhook, most recent first.

Path parameters

iduuid

required

Webhook UUID

Response

200 OK

{
  "data": [
    {
      "id": "del-001",
      "event_type": "order.created",
      "attempt_number": 1,
      "succeeded": true,
      "http_status": 200,
      "duration_ms": 142,
      "error_message": null,
      "created_at": "2025-06-24T09:01:00.000Z"
    },
    {
      "id": "del-002",
      "event_type": "stock.low",
      "attempt_number": 3,
      "succeeded": false,
      "http_status": 503,
      "duration_ms": 5000,
      "error_message": "Connection timeout",
      "created_at": "2025-06-24T08:00:00.000Z"
    }
  ]
}