Rotate a signing secret
Replace an endpoint's whsec_ secret without dropping events, using the dual-signature overlap.
Each endpoint has its own signing secret, whsec_…. It is shown once, when the endpoint is created or its secret rotated. ZyloPay stores it encrypted.
Rotate it on a schedule, when someone with access leaves, or at once if it may have leaked.
How the overlap works
When you rotate, ZyloPay issues a new secret and keeps signing with the old one for an overlap window: 24 hours by default, 0 to 168 hours. During the window every delivery carries two v1 signatures:
ZyloPay-Signature: t=1790604160,v1=<signature with the new secret>,v1=<signature with the old secret>A receiver that accepts a match with any v1 keeps working with either secret. secret_rotation_ends_at on the endpoint says when the old secret stops.
Steps
Rotate, in the dashboard (Rotate secret) or with the API:
const endpoint = await zp.webhookEndpoints.rotateSecret(
'we_2Lk9Qm4Xz7Pv1Rt8Wb3Ns6Hd',
{ expires_in_hours: 48 },
{ idempotencyKey: randomUUID() },
);
// endpoint.secret is the new whsec_… (shown once)Store the new secret in your secrets manager and deploy it to every instance of your receiver before secret_rotation_ends_at.
Send a test event and check that it verifies with the new secret.
If the old secret leaked, rotate with expires_in_hours: 0. The old secret stops at once; deliveries fail on receivers that still use it until you deploy the new one. Failed deliveries are retried for 3 days, so nothing is lost if you deploy within that time.
Receivers with several secrets
If you cannot deploy atomically, let your receiver try a list of secrets (new first, then old) and accept if any matches. Remove the old secret after the window ends.