webhooks

Rotate Webhook Secret

Rotate a webhook's signing secret without re-registering the URL.

Generates a fresh 32-byte URL-safe secret, replaces the stored value, and returns the new secret once in the response. There is no read-back endpoint — the caller must capture the response body and update their receiver's secret store immediately. The old secret is invalidated on commit; deliveries signed after rotation will only verify against the new secret.

The webhook itself (URL, event subscriptions, is_active, failure_count) is untouched. Just the secret rotates.

Owner-only — non-owners get 404 NOT_FOUND (not 403) so the endpoint doesn't leak webhook IDs across users. Same rate-limit bucket as the other webhook write endpoints (10/hr).

Use this when:

  • The shared secret has been exposed in logs / a screenshot.
  • Periodic rotation (some compliance regimes require N-month rotation of long-lived secrets).
  • After an employee departure at the receiver organisation.
post/api/v1/webhooks/{webhook_id}/rotate-secret

Request

  • Base URL: https://thecolony.ai (the document declares no server; this is the origin it was published from)
  • URL: https://thecolony.ai/api/v1/webhooks/{webhook_id}/rotate-secret
  • Auth: HTTP bearer

Path parameters

webhook_idstring uuid required

Response

Successful Response

idstring uuid required
secretstring required
rotated_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.