Webhook subscriptions

Update a webhook subscription

Copy page

Applies an RFC 7396 JSON Merge Patch to topic and/or url. Omitted fields remain unchanged; null, read-only, and unknown fields are rejected.

PATCH/api/v3/webhook-subscriptions/{webhook_id}

Update a webhook subscription

Applies an RFC 7396 JSON Merge Patch to `topic` and/or `url`. Omitted fields remain unchanged; null, read-only, and unknown fields are rejected. Requires `webhooks:write` and an `Idempotency-Key`. A patch that sends `topic` also requires the read scope of that topic. A patch that sends only `url` requires the read scope of the current topic. The API does not check existing subscriptions again.

Update a webhook subscription

Overview

Requires webhooks:write and an Idempotency-Key. A patch that sends topic also requires the read scope of that topic. A patch that sends only url requires the read scope of the current topic. The API does not check existing subscriptions again.

Authorisation

Bearer token required. Include it in the Authorization header.

Required scope: webhooks:write

Path parameters

webhook_idstringpathrequired

The canonical subscription ID.

Example: 1

Request body

topicstringbody

urlstringbody

Request body example

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

Update a webhook subscription

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

{
  "data": {
    "object": "webhook_subscription",
    "id": 42,
    "topic": "order:created",
    "url": "https://example.com/webhooks/sign-customiser-v2",
    "created_at": "2026-07-22T00:00:00Z",
    "updated_at": "2026-07-22T00:05: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/resource_not_found",
  "title": "Resource not found",
  "status": 404,
  "code": "resource_not_found",
  "detail": "The requested resource does not exist or does not belong to the authenticated store.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/provider_managed_subscription",
  "title": "Provider-managed subscription",
  "status": 409,
  "code": "provider_managed_subscription",
  "detail": "This subscription is managed by its integration provider and cannot be changed through API v3.",
  "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": "required",
      "detail": "The url field is required when present and cannot be null."
    }
  ],
  "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"
}