---
{
  "id": "platform.webhook.secret-rotation",
  "topic": "webhook",
  "title": "Rotate a webhook signing secret",
  "locale": "en",
  "version": "2026-08-09",
  "summary": "Rotation immediately invalidates the old secret, has no grace period, and returns the replacement secret only once after confirmation.",
  "content": "`arinova.webhook.rotate_secret` has an immediate, webhook-wide blast radius. There is no grace period and no dual-secret overlap: as soon as rotation commits, every sender still using the old secret fails signature verification.\n\nThe action requires this Agent's per-Webhook `write` grant, explicit user confirmation, and strict drift protection so a confirmation cannot be replayed for a different webhook intent. Missing and unauthorized resources both return `resource_not_found`. The replacement `signingSecret` is display-once. It is returned to the live caller, redacted from persisted action results, and cannot be recovered later through get or list.\n\nBefore rotating in Office > Incoming Webhooks or through the confirmed Action, identify every sender deployment, prepare a coordinated secret update, and ensure the operator can capture the new value into a secret manager. After confirmation, rotate once, distribute the new secret through the prepared deployment path, and test a newly signed event. Do not promise uninterrupted delivery unless the senders can be updated immediately; Arinova does not keep the old credential valid during rollout.\n\nIf the new plaintext value is lost, perform another confirmed rotation. Never ask the user to paste a production signing secret into chat or store it in Platform Knowledge.\n",
  "aliases": [
    "rotate webhook secret",
    "signing key rotation",
    "replace credential",
    "old secret",
    "grace period",
    "compromised secret"
  ],
  "tags": [
    "confirmation",
    "display-once",
    "lifecycle",
    "security"
  ],
  "relatedActions": [
    "arinova.webhook.rotate_secret",
    "arinova.webhook.get_webhook"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/en/kb/webhook/secret-rotation/"
}
---

`arinova.webhook.rotate_secret` has an immediate, webhook-wide blast radius. There is no grace period and no dual-secret overlap: as soon as rotation commits, every sender still using the old secret fails signature verification.

The action requires this Agent's per-Webhook `write` grant, explicit user confirmation, and strict drift protection so a confirmation cannot be replayed for a different webhook intent. Missing and unauthorized resources both return `resource_not_found`. The replacement `signingSecret` is display-once. It is returned to the live caller, redacted from persisted action results, and cannot be recovered later through get or list.

Before rotating in Office > Incoming Webhooks or through the confirmed Action, identify every sender deployment, prepare a coordinated secret update, and ensure the operator can capture the new value into a secret manager. After confirmation, rotate once, distribute the new secret through the prepared deployment path, and test a newly signed event. Do not promise uninterrupted delivery unless the senders can be updated immediately; Arinova does not keep the old credential valid during rollout.

If the new plaintext value is lost, perform another confirmed rotation. Never ask the user to paste a production signing secret into chat or store it in Platform Knowledge.