rotate_webhook_endpoint_secret
Replace an endpoint's signing secret. The new secret is returned in this response only and the old one stops verifying at once.
Mint a new HMAC signing secret for an endpoint — because the old one leaked, because the consumer lost it, or on a rotation schedule. From this call on, every delivery to the endpoint is signed with the new secret and the previous one stops verifying.
Destructive, and the secret is returned once
Deliveries signed with the new secret start immediately, so a consumer still
checking the old one rejects everything until it is updated. Confirm the
endpoint_id with a human, have the new secret deployed straight from this
response, and never call it "to check" — every call mints another secret, and
none of them can be read back.
Only the creator who registered the endpoint, or the team owner, may rotate; a fellow team member is
refused with FORBIDDEN. Not idempotent.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
A client that honours annotations asks a person before running it.
Arguments
endpoint_id*stringUUID of the webhook endpoint whose secret to replace.
What it returns
{ "data": { "id": "c62a08f4-1b7d-4e35-9860-a37f5d21e0b9", "name": "CRM sync", "url": "https://hooks.example.com/subscriby", "project_id": null, "events": ["subscription.created", "subscription.cancelled"], "is_active": true, "disabled_at": null, "allowed_ips": [], "failure_count": 2, "consecutive_failures": 0, "last_success_at": "2026-09-05T18:00:00+00:00", "last_failure_at": "2026-08-30T07:12:00+00:00", "created_at": "2026-05-18T10:05:00+00:00", "secret": "whsec_..." }}How it fails
FORBIDDENthe token belongs to a team member who did not register the endpoint and is not the team owner.
VALIDATION_FAILEDthe rotation was refused for the endpoint's current state.
RESOURCE_NOT_FOUNDunknown endpoint_id, or an endpoint of another team.
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks webhook-endpoint:update.
How is this guide?
Last updated on