Webhook subscriptions

Create a webhook subscription

Copy page

Registers an HTTPS callback for one topic. Requires webhooks:write, the read scope of the topic and an Idempotency-Key.

POST/api/v3/webhook-subscriptions

Create a webhook subscription

Registers an HTTPS callback for one topic. Requires `webhooks:write`, the read scope of the topic and an `Idempotency-Key`. The read scope is `orders:read` for `order:created`, `products:read` for `product:created` and `quotes:read` for `form:submitted`. If the key does not have the read scope, the request fails with `403 insufficient_scope`. The response contains the signing `secret`; store it securely because later subscription responses never return it. Verify deliveries using https://www.signcustomiser.com/help/integrations/subscribe-to-webhooks/. Retrying the exact request and key replays the original response without creating a second subscription or rotating the secret. Registration does not itself enable delivery: `product:created` and `order:created` emit only for Stores with custom API access. Contact Sign Customiser support to confirm eligibility if those events do not arrive.

Create a webhook subscription

Overview

The read scope is orders:read for WEBHOOKorder:created, products:read for WEBHOOKproduct:created and quotes:read for WEBHOOKform:submitted. If the key does not have the read scope, the request fails with 403 insufficient_scope. The response contains the signing secret; store it securely because later subscription responses never return it. Verify deliveries using https://www.signcustomiser.com/help/integrations/subscribe-to-webhooks/. Retrying the exact request and key replays the original response without creating a second subscription or rotating the secret. Registration does not itself enable delivery: WEBHOOKproduct:created and WEBHOOKorder:created emit only for Stores with custom API access. Contact Sign Customiser support to confirm eligibility if those events do not arrive.

Authorisation

Bearer token required. Include it in the Authorization header.

Required scope: webhooks:write

Request body

topicstringbody

urlstringbody

Request body example

{
  "topic": "product:created",
  "url": "https://example.com/webhooks/sign-customiser"
}

Create a webhook subscription

curl https://web.signcustomiser.com/api/v3/webhook-subscriptions \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "topic": "product:created",
  "url": "https://example.com/webhooks/sign-customiser"
}'

{
  "data": {
    "object": "webhook_subscription",
    "id": 42,
    "topic": "product:created",
    "url": "https://example.com/webhooks/sign-customiser",
    "created_at": "2026-07-22T00:00:00Z",
    "updated_at": "2026-07-22T00:00:00Z"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/webhook-subscriptions/42",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_idempotency_key",
  "title": "Missing idempotency key",
  "status": 400,
  "code": "missing_idempotency_key",
  "detail": "Provide an Idempotency-Key header for this write.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key",
  "title": "Missing API key",
  "status": 401,
  "code": "missing_api_key",
  "detail": "Provide a store API key as a bearer token.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This operation requires the webhooks:write scope.",
  "required_scopes": [
    "webhooks:write"
  ],
  "granted_scopes": [
    "webhooks:read"
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict",
  "title": "Idempotency key conflict",
  "status": 409,
  "code": "idempotency_key_conflict",
  "detail": "This Idempotency-Key was already used for a different request body on this operation.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/request_too_large",
  "title": "Request too large",
  "status": 413,
  "code": "request_too_large",
  "detail": "The request body must not exceed 2 MiB.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "The request payload failed validation.",
  "errors": [
    {
      "pointer": "/url",
      "code": "safe_outbound_url",
      "detail": "The url must be a public HTTPS URL."
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "You have exceeded the request limit for this API key.",
  "retry_after": 60,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}