Cowdidocs
API ReferenceWebhooks

Rotate the signing key

POST
/v1/webhooks/{webhookId}/secrets

Mints a second key so a receiver can accept both while it rolls over. Revoke the old key with the revoke a signing key operation once it has. A webhook holds at most two keys, so rotating twice without revoking is a conflict. Requires the org:connect:write permission. Returns 404 when the caller's organization has no webhook with this id, and 409 when the webhook already holds the maximum number of keys.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Path Parameters

webhookId*string

Unique identifier of the webhook.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/webhooks/550e8400-e29b-41d4-a716-446655440000/secrets"
{  "id": "550e8400-e29b-41d4-a716-446655440001",  "secret": "whsec_examplekey_abc123def456ghi789",  "masked_secret": "whsec_...a1b2",  "created_at": "2026-09-01T10:15:30Z"}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "code": "BAD_REQUEST",  "description": "Invalid input"}
{  "code": "BAD_REQUEST",  "description": "Invalid input"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Delete a webhook DELETE

Deletes the webhook and its signing keys. Existing delivery records stay available. An active delivery finishes before deletion returns. Requires the `org:connect:write` permission. Returns 404 when the caller's organization has no webhook with this id.

Revoke a signing key DELETE

Revokes a key the receiver has stopped using. The last remaining key cannot be revoked, because a webhook that cannot sign sends deliveries that a receiver refuses. Requires the `org:connect:write` permission. Returns 404 when the caller's organization has no webhook with this id, or the webhook has no such key, and 409 when this is the only key the webhook has.