> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apps.lute.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Receive real-time notifications for order events, tracking scans, and delivery milestones.

# 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.

> [card] [Event Catalogue](https://docs.apps.lute.co.in/webhooks/events.md)
>
> Browse all supported event types and sample JSON payloads.

> [card] [Courier Webhooks](https://docs.apps.lute.co.in/webhooks/courier-webhooks.md)
>
> 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:

```http theme={null}
POST /your-webhook-endpoint HTTP/1.1
Host: api.yourdomain.com
Content-Type: application/json
X-Shipdesk-Signature: t=1700670000,v1=5d41402abc4b2a76b9719d911017c592
```

### 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:
   ```
   signed_payload = t + "." + raw_request_body
   ```
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

```javascript theme={null}
import crypto from 'crypto';

export function verifyShipdeskWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(part => part.split('='))
  );
  const timestamp = parts.t;
  const expectedSig = parts.v1;

  // Prevent replay attacks (reject timestamps older than 5 minutes)
  const fiveMinutesAgo = Math.floor(Date.now() / 1000) - 300;
  if (parseInt(timestamp, 10) < fiveMinutesAgo) {
    throw new Error('Webhook timestamp too old');
  }

  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(`${timestamp}.${rawBody}`).digest('hex');

  const valid = crypto.timingSafeEqual(
    Buffer.from(digest),
    Buffer.from(expectedSig)
  );

  if (!valid) throw new Error('Invalid webhook signature');
}
```

***

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.