Rotates a webhook's secret by creating a new secret.

The old secret stays active for the number of seconds you pass in meta.expires-in-seconds. If you omit it, it defaults to 0: the old secret expires immediately and there is no overlap, so deliveries signed only with the new secret start right away. To rotate without downtime, set expires-in-seconds long enough to cover deploying the new secret to your endpoint.

Signatures during rotation

While both secrets are active, Persona signs every webhook event with each of them. The Persona-Signature header then contains one t=<unix_timestamp>,v1=<signature> set per active secret, separated by a space:

t=1764686826,v1=<signature_from_one_secret> t=1764686826,v1=<signature_from_the_other_secret>

The order of the sets is not guaranteed. Your handler must check every v1 signature in the header and accept the request if any of them matches. Once the old secret expires, the header contains a single set again.

Rotating without downtime

1. Update your handler to check every v1 signature in the Persona-Signature header, as described in Checking signatures.
2. Call this endpoint with an expires-in-seconds long enough to cover your deployment.
3. Deploy the new secret to your endpoint.
4. Let the old secret expire.

A webhook can have only one expiring secret at a time. Calling this endpoint again while the old secret is still active does not create another secret. Instead, it moves the old secret's expiration to expires-in-seconds from now, which can only make it sooner (pass 0 to expire it immediately).

For more details, see Rotating secrets safely and Quickstart: Webhooks.