Webhook subscriptions

This page covers only the management endpoints. For the wire format and event payloads see Webhooks.

The WebhookSubscription object:

The signingKey field is never returned by GET. It's surfaced exactly once in the response of a successful POST (create or rotate).

The WebhookDelivery object:

GET /api/v1/webhooks

List webhook subscriptions for the tenant.

Required scope — webhooks:read

Response 200

{ "data": [ /* WebhookSubscription[] */ ] }

Errors — 401, 403 (scope-required, or plan-required when the plan has no API access), 429.

POST /api/v1/webhooks

Create a webhook subscription. The plaintext signingKey is returned exactly once in the response. Lose it and you rotate it (below).

Required scope — webhooks:write

Request body

Response 201

{
  "data": /* WebhookSubscription */,
  "signingKey": "zyXBHGFEDCBA9876…"
}

The signing key is the value passed to your verifier — see Signing.

Errors — 401; 403 for all three refusals — scope-required, forbidden with code: "feature_off_for_tier" (webhooks are not on this plan) and forbidden with code: "webhook_quota_exceeded" (the per-plan endpoint cap is full); 422 validation-failed (bad URL shape, unknown event type, non-HTTPS, private IP); 429.

DELETE /api/v1/webhooks/{id}

Soft-delete a subscription. We set active=false and pausedAt=now(); the row and its delivery history are retained.

Required scope — webhooks:write

Path parameters

Response 204 — empty body.

Errors — 401, 403 scope-required, 404 not-found.

POST /api/v1/webhooks/{id}/rotate-key

Mint a new signing key. For the next 24 hours every delivery is signed with both keys (t=…,v1=<new>,v1=<old>), so you can roll your verifier over without dropping events. After the window the old key stops signing.

Required scope — webhooks:write

Response 200

{
  "data": /* WebhookSubscription */,
  "signingKey": "newPlaintext…",
  "legacySigningKeyExpiresAt": "2026-05-27T12:00:00.000Z"
}

Errors — 401, 403 scope-required, 404 not-found, 429.

GET /api/v1/webhooks/{id}/deliveries

List delivery rows for a subscription, newest first. Cursor-paginated like every list endpoint: pass limit and cursor, and read the next cursor back out of meta.

Required scope — webhooks:read

Query parameters

Response 200

{ "data": [ /* WebhookDelivery[] */ ], "meta": { "cursor": "…", "hasMore": true } }

Errors — 401, 403 scope-required, 404 not-found, 429.

POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver

Queue a fresh delivery of the same event. Creates a new delivery row with the same Tourical-Event-Id; the original row is untouched. Safe for consumers that dedupe on the event id.

Required scope — webhooks:write

Response 202

{ "data": { "deliveryId": "whd_new…", "eventId": "7d3f0e2c-…", "status": "pending" } }

Errors — 401, 403 scope-required, 404 not-found (subscription or delivery outside your tenant), 409 conflict with code: "in_flight" (an attempt is running right now) or code: "subscription_inactive" (paused or deleted — re-enable first), 429.

POST /api/v1/webhooks/test

Fire a synthetic webhook.test event so you can verify your signature handling end-to-end. The test payload is shaped identically to a real one (see the catalog).

Required scope — webhooks:write

Request body — optional

Response 200

{
  "data": {
    "eventId": "7d3f0e2c-9aa1-4f2c-bd56-1c4a8e4f0b91",
    "deliveries": 1
  }
}

deliveries is the number of delivery rows created. Follow the outcome with GET /v1/webhooks/{id}/deliveries or in the dashboard.

Errors — 401, 403 (scope-required, or plan-required when the plan has no API access), 404 not-found (unknown subscriptionId, or one outside your tenant), 422 validation-failed, 429.