AXaxilioai
webhooks

Rotate a webhook endpoint's signing secret

Changed on

Issues a new signing secret for the endpoint, returned exactly once. With mode graceful (the default) the previous secret keeps verifying for 24 hours (previous_secret_invalid_at in the response) so the new secret can be rolled out across a deploy without dropping deliveries in flight. With mode immediate the previous secret stops verifying at once, for a secret that may be compromised. A missing or wrong-organization id returns 404.

post/webhooks/endpoints/{endpoint_id}:rotateSecret

Request

Path parameters

endpoint_idstring required

Endpoint identifier.

Request body

$schemastring uri

A URL to the JSON Schema for this object.

mode'graceful' | 'immediate'

graceful: the previous secret keeps verifying for 24 hours so the new one can be rolled out across a deploy. immediate: the previous secret stops verifying at once, for a secret that may be compromised. Omit for graceful.

Example request

{
  "$schema": "/api/v1/WebhookRotateSecretRequest.json"
}

Response

OK

$schemastring uri

A URL to the JSON Schema for this object.

idstring required

Endpoint identifier.

previous_secret_invalid_atstring date-time

When the previous signing secret stops verifying: 24 hours out for a graceful rotation, already past for an immediate one. Until then both the old and new secret verify.

secretstring required

New Standard Webhooks signing secret (whsec_...). Shown once and never returned again.

Example response

{
  "$schema": "/api/v1/WebhookRotateSecretResponse.json"
}

Changes