import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.webhooks.rotateSecret(
  "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.rotate_webhook_secret(
    "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
)
print(result)

curl -X POST 'https://api.mails.ai/v1/webhooks/whe_01JZX8K3M9Q4P7VN2YB6RTDC0E/rotate-secret' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails webhooks rotate-secret whe_01JABC

{
  "name": "mails_webhooks_rotate_secret",
  "arguments": {
    "webhook_id": "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E"
  }
}

{
  "id": "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "signing_secret": "<signing_secret>",
  "secret_rotated_at": "2026-10-04T12:00:00.000Z",
  "previous_secret_expires_at": "2026-10-04T12:00:00.000Z"
}

200  The new secret and when the previous one stops
     signing.
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
429  Rate or quota limit exceeded. The body's resets_at
     and retry_after_seconds say when the request can
     succeed. A Retry-After header is sent only when
     that is 60 seconds or less; a longer wait (an
     hourly, daily or monthly cap) sends none, so retry
     at resets_at or raise the limit instead of
     sleeping.
500  Internal server error.

Rotate the signing secret

Issues a new signing secret, returned once.

POST/v1/webhooks/{id}/rotate-secretscope · manage

import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.webhooks.rotateSecret(
  "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.rotate_webhook_secret(
    "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
)
print(result)

curl -X POST 'https://api.mails.ai/v1/webhooks/whe_01JZX8K3M9Q4P7VN2YB6RTDC0E/rotate-secret' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails webhooks rotate-secret whe_01JABC

{
  "name": "mails_webhooks_rotate_secret",
  "arguments": {
    "webhook_id": "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E"
  }
}

{
  "id": "whe_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "signing_secret": "<signing_secret>",
  "secret_rotated_at": "2026-10-04T12:00:00.000Z",
  "previous_secret_expires_at": "2026-10-04T12:00:00.000Z"
}

200  The new secret and when the previous one stops
     signing.
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
429  Rate or quota limit exceeded. The body's resets_at
     and retry_after_seconds say when the request can
     succeed. A Retry-After header is sent only when
     that is 60 seconds or less; a longer wait (an
     hourly, daily or monthly cap) sends none, so retry
     at resets_at or raise the limit instead of
     sleeping.
500  Internal server error.

Path Parameters

idstringrequired

Webhook endpoint id.

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.

Response

idstring

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

signing_secretstring

The new HMAC signing secret. SHOWN ONCE.

secret_rotated_atstring

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

previous_secret_expires_atstring

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

Was this page helpful?