Skip to main content

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 the X-Shipdesk-Signature header so your server can verify that the payload originated from Shipdesk:

Signature Verification Algorithm

  1. Extract the timestamp t and signature v1 from the X-Shipdesk-Signature header.
  2. Form the signature payload by concatenating t, a period ., and the raw request body string:
  3. Compute the HMAC using SHA-256 with your webhook secret key (whsec_... from Settings).
  4. Compare your calculated hexadecimal signature with v1 using constant-time string comparison.

Node.js Verification Example


Retry Policy & Delivery Guarantees

  • Timeout: Your endpoint must respond with an HTTP 2xx status code within 5 seconds.
  • Retries: If your server responds with an error (4xx or 5xx) 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 id field. Your webhook consumer should be idempotent and ignore duplicate delivery of already-processed event IDs.