{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Secret rotation","description":"Start today using our public API to power your next project."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"secret-rotation"},"children":["Secret rotation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rotate your signing secret on a regular schedule, and immediately if you suspect it has leaked."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /v1/webhooks/subscriptions/{id}/rotate-secret\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response contains the new secret and the expiry of the old one:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\":                     \"a1b2c3d4-...\",\n  \"secret\":                 \"whsec_newSecretValue...\",\n  \"previousSecretExpiresAt\": \"2026-04-21T10:00:00.000Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"zero-downtime-rotation"},"children":["Zero-downtime rotation"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1.-call-rotate-secret"},"children":["1. Call rotate-secret"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Capture the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["previousSecretExpiresAt"]}," from the response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2.-deploy-the-new-secret"},"children":["2. Deploy the new secret"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your signature verifier already accepts either of the two signatures present in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Signature"]}," during the grace period."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3.-decommission-the-old-secret"},"children":["3. Decommission the old secret"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["previousSecretExpiresAt"]},", only the new secret is valid. Remove the old one from your secret store."]}]},"headings":[{"value":"Secret rotation","id":"secret-rotation","depth":1},{"value":"Zero-downtime rotation","id":"zero-downtime-rotation","depth":2},{"value":"1. Call rotate-secret","id":"1.-call-rotate-secret","depth":3},{"value":"2. Deploy the new secret","id":"2.-deploy-the-new-secret","depth":3},{"value":"3. Decommission the old secret","id":"3.-decommission-the-old-secret","depth":3}],"frontmatter":{"seo":{"title":"Secret rotation"}},"lastModified":"2026-06-15T18:50:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/integration-guides/webhooks/secret-rotation","userData":{"isAuthenticated":false,"teams":["anonymous"]}}