# Deliverect Webhooks

Deliverect is an order and menu hub between ordering channels, POS systems and couriers. A
partner integration (channel, POS, dispatch, retail) receives Deliverect's calls on the URLs it
registers; a channel's `/register` response returns one URL per webhook kind (for example
`statusUpdateURL`, `menuUpdateURL`, `snoozeUnsnoozeURL`, `busyModeURL`). Each call carries an
HMAC-SHA256 signature of the raw request body in `x-server-authorization-hmac-sha256`.

## When to Use This Skill

* How do I receive Deliverect webhooks?
* How do I verify the `x-server-authorization-hmac-sha256` header?
* What secret does Deliverect sign with before and after certification?
* Why does my Deliverect GET request have no body, and how is it signed?
* How do I handle order status, menu update, snooze/unsnooze or busy-mode calls?
* Why is my Deliverect signature verification failing?

## Setup Note

Paste the HMAC secret from your Deliverect integration settings. Before certification, Deliverect signs with the channelLink or locationId value instead. Some Deliverect calls are GET requests, so also allow GET on this source if your integration receives them.

Hookdeck's Deliverect source accepts only the methods you allow ([custom methods](https://hookdeck.com/docs/sources#custom-methods)), so any other method
the sender uses (GET, PUT, PATCH, DELETE) must also be allowed on the source.

## Verification (core)

```javascript
const crypto = require('crypto');

// rawBody: Buffer of the body exactly as received (empty Buffer for a GET with no body)
function verifyDeliverectSignature(rawBody, signature, secret = process.env.DELIVERECT_WEBHOOK_SECRET) {
  if (!secret || typeof signature !== 'string') return false;
  if (!/^[0-9a-fA-F]{64}$/.test(signature)) return false;      // validate before decoding
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest(); // key = UTF-8 bytes
  const received = Buffer.from(signature.toLowerCase(), 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}
// signature = req.headers['x-server-authorization-hmac-sha256']  (bare hex, no prefix)

```

* **Header:** `x-server-authorization-hmac-sha256`, the whole value is one lowercase hex digest. No prefix, no list.
* **Signed content:** the raw body bytes only. No timestamp, id or other header is signed, so there is no
  replay window to check. Never parse and re-serialize the body before verifying.
* **GET requests** have no body: the HMAC is computed over the empty string, so verify over zero bytes.
* **Secret:** used as UTF-8 bytes, not hex- or base64-decoded. It is one secret per environment (see below).
* Return `401` for a missing, empty or malformed header or a mismatch; `200` once handled. A verified
  request with an empty body is acknowledged with `200`.
* Accept `GET`, `POST`, `PUT`, `PATCH` and `DELETE` on the route and verify first for every method.
  In Express read the body with `express.raw({ type: '*/*' })`; in Next.js use `request.arrayBuffer()`;
  in FastAPI use `await request.body()`.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/deliverect-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/deliverect-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/deliverect-webhooks/examples/fastapi/).

## Which Secret?

| Environment | Secret |
| --- | --- |
| Staging, before certification | The call's `channelLink` (present in most calls to partner endpoints), or `locationId` for Dispatch API integrations and the POS Get Products webhook |
| Production, certified partner | The HMAC secret generated in your Deliverect Integration settings |

## Webhook Kinds

Deliverect has no event-name field or header: the kind of call is chosen by the URL you registered.
The examples use one route and an **optional path segment** (`/webhooks/deliverect/<kind>`) to tell
kinds apart. The kind names and body fields below are illustrative; confirm the payloads for your
integration type in the [Deliverect docs](https://developers.deliverect.com).

| Kind (path segment) | Registered as | Typical purpose |
| --- | --- | --- |
| `order_status_update` | `statusUpdateURL` | Order status changes |
| `menu_update` | `menuUpdateURL` | Menu publish/update |
| `snooze_unsnooze` | `snoozeUnsnoozeURL` | Items snoozed or unsnoozed |
| `busy_mode` | `busyModeURL` | Location paused or put online |

Each operational webhook expects a `200 OK`. Retry and timeout behaviour is not documented on the pages this skill was built from.

## Environment Variables

```bash
DELIVERECT_WEBHOOK_SECRET=your_hmac_secret   # production secret, or channelLink / locationId before certification

```

## Local Development

Deliverect can't reach `localhost`. Tunnel with the Hookdeck CLI (no account required):

```bash
npx hookdeck-cli listen 3000 deliverect --path /webhooks/deliverect

```

Register the printed URL (plus a kind segment if you want one) as the matching webhook URL.

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/deliverect-webhooks/references/overview.md) - What Deliverect webhooks are, methods and webhook kinds
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/deliverect-webhooks/references/setup.md) - Secrets, registering URLs, allowing methods on the Hookdeck source
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/deliverect-webhooks/references/verification.md) - Signature details, gotchas, debugging 401s
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/deliverect-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests