Webhook deliveries, retries and signatures
Every webhook delivery is signed, retried when your server fails, and logged.
- Plan
- Depends on your plan · Which plan do I need?
- Who can use this
- Developer
Every webhook delivery is signed, retried when your server fails, and logged.
Every webhook delivery is signed, retried when your server fails, and logged. This page shows how to check a signature, how retries and automatic disabling work, and how to retry or replay events from the panel.
Settings → App → Developers, then in the Webhooks sidebar:
Each endpoint also has its own Overview, Deliveries and Events tabs. You need the Manage Webhooks permission.
Each delivery carries Webhook-Signature: t=<unix seconds>,v1=<hex>.
During a secret rotation there are two v1 values for 24 hours; accept either.
The developer portal page Checking signatures has ready code for Node.js, Python, PHP and Go. The scheme is like Stripe's, not the Standard Webhooks format, so do not use a Standard Webhooks library.
Retry is offered for failed and expired deliveries. A new attempt starts at once.
| Header | Meaning |
|---|---|
Webhook-Signature | t=…,v1=… |
Webhook-Id | The event id. Same on every retry and replay: deduplicate on this |
Webhook-Event-Id | Same value as Webhook-Id |
Webhook-Delivery-Id | This attempt only. New on every try (also sent as Idempotency-Key) |
Webhook-Event-Type | For example contact.created |
Webhook-Event-Version | Payload version, for example 1 |
Webhook-Event-Occurred-At | When it happened |
Webhook-Api-Version | Your endpoint's API version |
Each delivery also carries older Wc-* copies of these headers. Use the Webhook-* names. In particular, Wc-Webhook-Id is the delivery id, not the event id, so never deduplicate on it.
These values are fixed by the platform:
5xx, 408 and 429.4xx, and addresses blocked as private or internal.Retry-After header in your answer is honoured, up to 24 hours.endpoint.disabled event is sent. A 429 does not count toward this, and any success resets the count.Webhook-Id values you have handled and skip repeats.Do it with Copilot
Do it with Copilot
Do it with Copilot
Do it with Copilot
(needs approval)
Do it with Copilot
(needs approval)
| What you see | Why | What to do |
|---|---|---|
| Your server rejects every signature | Body was parsed or re-encoded before hashing, or the whsec_ prefix was dropped | Hash the raw bytes with the full secret |
| Signatures fail after a rotation | Server still has only the old secret and 24 hours have passed | Deploy the new secret |
| Timestamp check fails | Server clock is wrong | Sync the clock (NTP) |
| Status Disabled (auto) | 15 failures in a row | Fix the server, turn the endpoint on, replay missed events |
Delivery failed with blocked_destination | The URL points to a private or internal address | Use a public HTTPS host |
| "Retry failed" | The delivery or endpoint no longer exists, or the server refused | Refresh; check the endpoint is active |
| "Replay failed" | The server refused the replay | Check the endpoint is active and subscribed |
| The same event arrives twice | A retry or replay | Deduplicate on Webhook-Id |