Webhook subscriptions

Create a webhook subscription

Copy page

Registers an HTTPS callback for one topic. Requires webhooks:write and an Idempotency-Key.

POST/api/v3/webhook-subscriptions

Create a webhook subscription

Registers an HTTPS callback for one topic. Requires `webhooks:write` and an `Idempotency-Key`. 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 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 theAuthorization 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"
}