Rotate a webhook’s secret

POST/webhooks/{webhookId}/rotate-secret

Signed inIdempotency-Key

A new signing secret, shown once. With graceHours 24, deliveries are signed with both secrets for a day, so your receiver can switch over.

SDK method: collector.rotateMyWebhookSecret()
Key scopes: webhooks:write
Headers: Idempotency-KeyX-Request-Id

Path parameters

webhookIdstring (uuid)required

Request body required · application/json

RotateWebhookSecret

graceHours"0" or "24"
Keep signing with the old secret too for this many hours, so your receiver can switch over.
default 0
ShowHide the fields of graceHours
1. Option 1: "0"
2. Option 2: "24"

Responses

201CreatedThe webhook and its new secret (shown once).

NewWebhook

A webhook just made, or its secret just rotated: the only time the secret is shown.

webhookWebhookrequired
secretstringrequired
The signing secret (whsec_…). Store it now: it can’t be shown again. Verify each delivery with it.

8Errors400 · 401 · 404 · 409 · 413 · 422 · 429 · 500

400
invalid_request invalid_json invalid_idempotency_key
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404
not_found
not_found: Nothing at that address.
409
idempotency_in_progress
idempotency_in_progress: The first request with this key is still running.
413
payload_too_large
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
422
idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).

curl -X POST 'https://api.collection.id/v1/webhooks/1c9e8b7a-6d5f-4e3c-9b2a-1f0e9d8c7b6a/rotate-secret' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
    "graceHours": 24
  }'

{
  "webhook": {
    "id": "1c9e8b7a-6d5f-4e3c-9b2a-1f0e9d8c7b6a",
    "kind": "personal",
    "storeId": null,
    "url": "https://sheets.example.com/hooks/collection",
    "description": "Spreadsheet sync",
    "events": [
      "collection.item.created",
      "collection.item.updated",
      "hold.accepted"
    ],
    "status": "active",
    "disabledAt": null,
    "disabledReason": null,
    "secretHint": "whsec_…k3Vb",
    "previousSecretExpiresAt": "2026-10-13T15:04:05.123Z",
    "createdBy": {
      "id": "0e6b1c52-8f43-4b8e-9d0c-5a7e2f1b3c4d",
      "label": "Carol"
    },
    "createdAt": "2026-10-12T15:04:05.123Z",
    "updatedAt": "2026-10-12T15:04:05.123Z",
    "health": {
      "failureStreak": 0,
      "failingSince": null,
      "lastSuccessAt": "2026-10-12T15:04:05.123Z",
      "lastFailureAt": null
    }
  },
  "secret": "whsec_9pQ2mVb7Xc4LtR1nK8sW3yH6jF0dA5gZ2eU7Ik3Vb"
}

Responses

201CreatedThe webhook and its new secret (shown once).

NewWebhook

A webhook just made, or its secret just rotated: the only time the secret is shown.

webhookWebhookrequired
secretstringrequired
The signing secret (whsec_…). Store it now: it can’t be shown again. Verify each delivery with it.

8Errors400 · 401 · 404 · 409 · 413 · 422 · 429 · 500

400
invalid_request invalid_json invalid_idempotency_key
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404
not_found
not_found: Nothing at that address.
409
idempotency_in_progress
idempotency_in_progress: The first request with this key is still running.
413
payload_too_large
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
422
idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).

curl -X POST 'https://api.collection.id/v1/webhooks/1c9e8b7a-6d5f-4e3c-9b2a-1f0e9d8c7b6a/rotate-secret' \ -H "Authorization: Bearer $COLLECTOR_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H 'Content-Type: application/json' \ -d '{ "graceHours": 24 }'

{ "webhook": { "id": "1c9e8b7a-6d5f-4e3c-9b2a-1f0e9d8c7b6a", "kind": "personal", "storeId": null, "url": "https://sheets.example.com/hooks/collection", "description": "Spreadsheet sync", "events": [ "collection.item.created", "collection.item.updated", "hold.accepted" ], "status": "active", "disabledAt": null, "disabledReason": null, "secretHint": "whsec_…k3Vb", "previousSecretExpiresAt": "2026-10-13T15:04:05.123Z", "createdBy": { "id": "0e6b1c52-8f43-4b8e-9d0c-5a7e2f1b3c4d", "label": "Carol" }, "createdAt": "2026-10-12T15:04:05.123Z", "updatedAt": "2026-10-12T15:04:05.123Z", "health": { "failureStreak": 0, "failingSince": null, "lastSuccessAt": "2026-10-12T15:04:05.123Z", "lastFailureAt": null } }, "secret": "whsec_9pQ2mVb7Xc4LtR1nK8sW3yH6jF0dA5gZ2eU7Ik3Vb" }