> ## Documentation Index
> Fetch the complete documentation index at: https://help.bodharouteplanner.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Receive real-time notifications when events happen in Bodha.

Webhooks let your server receive HTTP POST requests whenever something happens
in your Bodha account — a route is dispatched, a stop is completed, an order
is created, and more.

## How it works

1. You register an HTTPS endpoint in the **Developer Portal** (Settings → Developer).
2. You choose which events to subscribe to.
3. When an event fires, Bodha sends a JSON POST to your endpoint with the event
   payload, signed with HMAC-SHA256 so you can verify authenticity.

## Endpoint requirements

| Requirement | Detail |
| - | - |
| **Protocol** | HTTPS only — HTTP endpoints are rejected |
| **Response** | Return `2xx` within **10 seconds** |
| **Idempotency** | You may receive the same event more than once — use the delivery `id` to deduplicate |

## Delivery & retries

Each delivery is recorded with its HTTP status, response body (first 4 KB),
and duration. If your endpoint returns a non-2xx status or times out:

* The delivery is marked as **failed**.
* The endpoint's `failureCount` increments.
* After **10 consecutive failures**, the endpoint is automatically disabled.
* You can retry any delivery manually from the Developer Portal or via the API.

> [!NOTE]
>
> Bodha does not automatically retry failed deliveries. Use the retry endpoint
> or the Developer Portal to replay a delivery.

## Payload shape

Every webhook POST has this structure:

```json theme={null}
{
  "event": "route.dispatched",
  "timestamp": "2026-10-28T14:30:00.000Z",
  "data": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "name": "North Bay Deliveries",
    "status": "dispatched",
    ...
  }
}
```

## Security headers

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `X-Bodha-Signature` | HMAC-SHA256 hex digest of the raw body |
| `X-Bodha-Event` | The event name (e.g. `route.dispatched`) |
| `User-Agent` | `Bodha-Webhooks/1.0` |

See [Verifying Signatures](https://help.bodharouteplanner.com/api-reference/webhooks/signatures.md) for verification
code in multiple languages.


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