Skip to main content

Secret Rotation and Testing

Rotating the secret​

Change the secret periodically, or immediately if you suspect it leaked.

Webhook secret rotation: after rotating, the old and new secrets both sign during a 24-hour overlap, so the header carries two v1 values, then the old secret stops24-hour overlap (0–72 allowed)Old secretwhsec_…a1B2New secretwhsec_…k9ZqtimeRotate secretOld secret stopsX-Etalasse-Signaturet=…,v1=oldt=…,v1=new,v1=oldt=…,v1=newInstall the new secret on your server123
(1) After you rotate, (2) the old and new secrets both sign, so the header carries two v1 values, (3) until the overlap ends and the old secret stops.

(1) After you rotate, (2) the old and new secrets both sign, so the header carries two v1 values, (3) until the overlap ends and the old secret stops.

  1. Open the endpoint detail and choose Rotate secret.
  2. Choose the overlap hours (0 to 72, default 24).
  3. Copy the new secret. As at creation, the new secret is shown only once.
  4. Install the new secret on your server before the overlap ends.

During the overlap, both the new and the old secret sign every delivery, so the header carries two v1 values. A server that checks all v1 values (code examples) can switch without downtime. The endpoint shows a Rotating status and when the old secret expires.

Overlap hoursEffect
0The old secret stops working immediately
1-72Two signatures until the time runs out
caution

With 0 hours, deliveries that your server still verifies with the old secret will fail. Use 0 only if the old secret leaked.

Sending a test​

The Send test button sends a webhook.test event with a sample order to the endpoint and shows the result right away: success or not, HTTP code, latency, error, and a response excerpt.

  • Sent once, with no retries.
  • Not counted toward the failure streak, whether it succeeds or fails, so a test never disables an endpoint.
  • Limited to 10 per minute per shop.
  • Appears in the log with kind test.

Errors you may see:

ErrorMeaning
TIMEOUTNo reply within 8 seconds
CONNECT_FAILEDCould not connect to the server
ADDRESS_BLOCKEDThe host name points to a disallowed address
HTTP_503 (and other codes)The server replied non-2xx with that code

The webhook.test event cannot be subscribed to; it only comes from the test button.