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.

Purpose

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.

Required ability

webhook-endpoint:update

Input schema

{
  "type": "object",
  "required": ["endpoint_id"],
  "properties": {
    "endpoint_id": {
      "type": "string",
      "description": "UUID of the webhook endpoint whose secret to replace."
    }
  }
}

Output shape

{
  "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_..."
  }
}

Example prompts

"Rotate the signing secret on webhook endpoint c62a08f4-1b7d-4e35-9860-a37f5d21e0b9 — it was pasted into a public channel." (confirm first)

"Mint a new secret for the CRM sync endpoint; I'll update the handler now."

"Quarterly rotation for the finance webhook."

Failure modes

FORBIDDEN — the token belongs to a team member who did not register the endpoint and is not the team owner.
VALIDATION_FAILED — the rotation was refused for the endpoint's current state.
RESOURCE_NOT_FOUND — unknown endpoint_id, or an endpoint of another team.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks webhook-endpoint:update.

test_webhook_endpoint — confirm the consumer verifies the new secret.
create_webhook_endpoint — the other place a secret is ever shown.
Webhook endpoints API — the REST equivalent.
Webhook security — how the signature is computed.