Skip to content
DevelopersBuild with YallaBuy
Merchant guide
HTTPS · Signed events

Rotating the signing secret

If the secret is lost or leaked, rotation issues a new one without interrupting deliveries — thanks to the 24-hour overlap window.

Start building
Reviewed against implementation
YOUR INTEGRATION, AT A GLANCE
Webhook delivery · Headers
POST /your-webhook-endpoint
Content-Type: application/json
webhook-event-type: order.created
webhook-id: <endpoint_id>
webhook-event-id: <event_id>
webhook-delivery-id: <delivery_id>
webhook-timestamp: <unix_seconds>
webhook-signature: v1=<hmac_sha256_hex>
See the implementation
On this page

01Rotation steps

  1. On the webhooks screen: pick the endpoint and request a secret rotation — a new whsec_ secret is shown exactly once, just like creation.
  2. Store it as CURRENT_SECRET, and put the old one in a PREVIOUS_SECRET variable.
  3. Deploy the updated configuration — deliveries keep working throughout because signatures verify against both secrets during the overlap.
  4. After 24 hours from rotation, remove the old variable from your configuration.

02The overlap window and the one-layer rule

  • The old secret moves to previous_secret and keeps verifying for 24 more hours — the overlap window.
  • After the 24 hours, the daily maintenance job clears the old secret — from then on only the new secret verifies.
  • The platform always signs with the CURRENT secret — the old one exists only for your verification.

Keep exploring

Verifying the signatureQuick start — your first webhookReceiver endpoint security requirements

COMPLETE YOUR INTEGRATION