Webhooks

Rotate the signing secret

Requires scope: manage. Issues a new signing secret, returned once. For the next 24 hours every delivery's X-Mails-Signature carries a v1 signature from the new secret and one from the previous secret, so a receiver can switch over without failing a delivery. Verify by accepting the header when any v1 matches. Rotating again within the 24 hours retires the oldest secret. Closed to apps connected by sign-in (403 connected_app_not_allowed), and to a key tied to one agent (403): use an API key not tied to an agent, or the mails CLI. If the mails CLI sign-in that rotated it (or made the key that did) is later ended because one of its refresh tokens was used twice, the secret is rotated again and the replaced one stops signing at once.

post/v1/webhooks/{id}/rotate-secret

Request

  • Base URL: https://api.mails.ai
  • URL: https://api.mails.ai/v1/webhooks/{id}/rotate-secret
  • Auth: HTTP bearer

Path parameters

idstring required

Webhook endpoint id.

Response

The new secret and when the previous one stops signing.

idstring required

Id of the endpoint whose secret was rotated (whe_…): the id in the path.

signing_secretstring required

The new HMAC signing secret. SHOWN ONCE.

secret_rotated_atstring date-time required

When this rotation happened; the endpoint's own secret_rotated_at now shows the same time.

previous_secret_expires_atstring date-time required

Until this time every delivery carries a signature from the previous secret as well, so receivers can switch over without dropping events.

Changes

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