Webhooks Architecture & Security
Webhooks allow your application to react in real time when shipments progress through carrier networks, when NDR events occur, or when orders are assigned. Instead of polling our API, Shipdesk pushes JSON payloads to your HTTPS endpoint.Event Catalogue
Browse all supported event types and sample JSON payloads.
Courier Webhooks
Configure inbound push tracking from Delhivery, Shadowfax, Xpressbees, and Ekart.
Webhook Signatures & Security
Every outbound webhook request sent by Shipdesk includes a cryptographic signature in theX-Shipdesk-Signature header so your server can verify that the payload originated from Shipdesk:
Signature Verification Algorithm
- Extract the timestamp
tand signaturev1from theX-Shipdesk-Signatureheader. - Form the signature payload by concatenating
t, a period., and the raw request body string: - Compute the HMAC using SHA-256 with your webhook secret key (
whsec_...from Settings). - Compare your calculated hexadecimal signature with
v1using constant-time string comparison.
Node.js Verification Example
Retry Policy & Delivery Guarantees
- Timeout: Your endpoint must respond with an
HTTP 2xxstatus code within 5 seconds. - Retries: If your server responds with an error (
4xxor5xx) or times out, Shipdesk retries delivery using exponential backoff:- Immediate retry (attempt 1)
- 1 minute later
- 5 minutes later
- 30 minutes later
- 2 hours later
- 6 hours later
- Idempotency: All webhook payloads include an
idfield. Your webhook consumer should be idempotent and ignore duplicate delivery of already-processed event IDs.