# Guide to Deliverect Webhooks: Features and Best Practices

Deliverect sits between restaurants' point-of-sale systems and the ordering channels and couriers they sell through. If you build one of those channels or POS integrations, Deliverect calls your API whenever something changes on the restaurant's side: an order moves to preparing or ready, the menu is updated, a product sells out and is snoozed, or the kitchen goes into busy mode. Those calls are Deliverect's webhooks, and each one carries an HMAC signature you should check.

This guide focuses on the channel integration flow, where Deliverect's webhooks are most visible, and on the HMAC scheme that all partner integrations share: which secret applies before and after certification, and why GET requests are signed too.

## What are Deliverect webhooks?

Deliverect doesn't send a single stream of typed events. Instead, it calls URLs that your integration has given it, one per purpose. For a channel integration, the flow begins when Deliverect sends `POST /register` with the location and channel link IDs. Your response returns the URLs Deliverect should use from then on:

| URL | Deliverect calls it when |
| --- | --- |
| `statusUpdateURL` | An order's status changes in the POS (for example accepted, preparing, ready or cancelled) |
| `menuUpdateURL` | A menu, with its availabilities, is pushed to your channel |
| `snoozeUnsnoozeURL` | Products are snoozed (made unavailable) or unsnoozed |
| `busyModeURL` | A location is paused or back online |
| `updatePrepTimeURL` | The preparation time changes (optional) |
| `courierUpdateURL` | A courier's status changes (optional) |

Deliverect later re-sends the `/register` call with `status=active` to start orders and `status=inactive` to stop them. POS and retail integrations register their own per-purpose URLs in a similar way. Retail POS partners, for example, receive an order notification webhook when an order has been picked and finalised.

Because the URL decides the kind of call, a receiver should route by path, not by a field in the body.

## Deliverect webhook features

| Feature | Details |
| --- | --- |
| Registration | URLs returned from `/register` (channels) or configured on the integration (POS, retail) |
| Routing | By the URL the call arrives on |
| Signature | hex HMAC-SHA256 |
| Signature header | `x-server-authorization-hmac-sha256` |
| Signed content | The raw JSON body, or an empty string for a GET with no body |
| Secret, staging | The call's `channelLink`, or `locationId` for Dispatch and the POS Get Products webhook |
| Secret, production | Generated in **Integration settings** after certification |
| Methods | Mostly `POST`, with some signed `GET` calls |
| Body | JSON |
| Response | `200 OK` for each call |

The pages that describe the HMAC scheme and the integration flows don't state a retry policy, a timeout or source IP addresses.

## Events and payloads

The payloads differ by URL and integration type and are described in each webhook's reference page in the [Deliverect developer docs](https://developers.deliverect.com). An order status call, for instance, carries the order and its new status, while a busy mode call carries the location's paused or online state.

Two practical points apply to all of them. First, there is no event type field, so log the path with every request to keep track of what each body means. Second, treat each field of a verified body as untrusted input and check its type before use, because you will be coding against reference pages rather than a fixed schema shared across all calls.

## Setting up Deliverect webhooks

### Choose the secret for each environment

One HMAC secret is provided per environment.

1. **Staging (before certification):** Deliverect signs with a temporary value, either
  
  * the call's `channelLink` (present in most calls to partner endpoints), or
  * the `locationId` (Dispatch API integrations and the POS Get Products webhook).
2. **Production (certified partners):** generate the HMAC secret in your Deliverect **Integration settings** and use that.

Store it on your server, for example as `DELIVERECT_HMAC_SECRET`. It is used as UTF-8 bytes exactly as written, with nothing decoded or trimmed.

### Register your URLs

For a channel integration, return one URL per kind from your `/register` handler. Pointing them at one route with a kind segment keeps verification in one place:

```
https://your-app.example.com/webhooks/deliverect/order_status_update
https://your-app.example.com/webhooks/deliverect/menu_update
https://your-app.example.com/webhooks/deliverect/snooze_unsnooze
https://your-app.example.com/webhooks/deliverect/busy_mode

```

Other integration types register their URLs in the places named in their Deliverect guides, and can reuse the same route.

### Receiving through Hookdeck

If you receive through Hookdeck, use the HMAC secret from your Deliverect integration settings as the Deliverect source's verification secret. Before certification, Deliverect signs with the `channelLink` or `locationId` value instead. Some Deliverect calls are GET requests, so if your integration receives them, also allow GET on the Hookdeck source.

Hookdeck's Deliverect source pre-selects `POST` but doesn't manage the method, which is why you can add `GET`. Because a staging integration signs with a value that changes per channel link, use a separate source for staging and production. To try calls locally, the [Hookdeck CLI](/docs/cli) forwards them with `npx hookdeck-cli listen 3000 deliverect --path /webhooks/deliverect`.

## Securing Deliverect webhooks

Compute an HMAC-SHA256 of the raw body using the environment's secret, encode it as hex, and compare it with `x-server-authorization-hmac-sha256` in constant time after checking that the header is 64 hex characters. For a `GET` with no body, the HMAC is over an empty string. The method is described on Deliverect's [HMAC authentication page](https://developers.deliverect.com/reference/hmac-authentication).

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

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-server-authorization-hmac-sha256'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

The route accepts `GET` and `POST`, substitutes an empty buffer when there is no body, and then routes by the kind segment of the path:

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

const app = express();

app.all('/webhooks/deliverect/:kind', express.raw({ type: '*/*' }), async (req, res) => {
  if (!['POST', 'GET'].includes(req.method)) return res.sendStatus(405);
  req.body = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
  const secret = process.env.DELIVERECT_HMAC_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  let payload = null;
  if (req.body.length) {
    try {
      payload = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.sendStatus(400);
    }
    if (!payload || typeof payload !== 'object') return res.sendStatus(400);
  }

  try {
    switch (req.params.kind) {
      case 'order_status_update':
        await applyOrderStatus(payload);
        break;
      case 'menu_update':
        await queueMenuImport(payload);
        break;
      case 'snooze_unsnooze':
      case 'busy_mode':
        await updateAvailability(req.params.kind, payload);
        break;
      default:
        break;
    }
  } catch {
    return res.sendStatus(503);
  }

  res.sendStatus(200);
});

```

`applyOrderStatus`, `queueMenuImport` and `updateAvailability` stand for your own logic. Menu pushes can be large, so a real receiver should store them and import them after responding.

No timestamp is signed, so the HMAC proves origin and integrity but not freshness. Hookdeck's Deliverect source checks the same header and HMAC, including the empty-string case for a bodiless `GET`. It acknowledges every request with `200` and records a verification failure on the request rather than answering `401`.

> **Make Deliverect webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies Deliverect's HMAC on order, menu and availability calls, records which URL each one arrived on, and delivers them to your services with retries you control.

## Deliverect webhook limitations and pain points

### The staging secret isn't secret

**The Problem:** Before certification, anyone who knows a channel link ID can produce valid signatures.

**Why It Happens:** Deliverect signs staging calls with `channelLink` or `locationId`, values that also appear in the calls themselves.

**Workarounds:**

* Treat staging verification as a correctness check, not as security.
* Generate the production secret in Integration settings as soon as you are certified, and never reuse staging configuration in production.

**How Hookdeck Can Help:** Separate Hookdeck sources for staging and production keep the two secrets apart, and the production source can be locked to the real HMAC secret from day one.

### GET calls are signed over nothing

**The Problem:** Verification fails, or the handler crashes, on Deliverect's `GET` calls.

**Why It Happens:** Some calls are `GET` with no body, and the HMAC is computed over an empty string. In Express, `req.body` is not a buffer when there is no body, and routes defined with `app.post` never see the request.

**Workarounds:**

* Accept `GET` on the route, use an empty buffer when there is no body, and verify it like any other request.
* Don't try to parse JSON from a bodiless request.

**How Hookdeck Can Help:** Hookdeck's Deliverect source verifies the empty-string HMAC for you once `GET` is allowed on the source.

### No event name in the request

**The Problem:** A request logged without its URL is hard to interpret later.

**Why It Happens:** Deliverect identifies the kind of call by the URL you registered, not by a field in the body or a header.

**Workarounds:**

* Use a distinct path per kind, and log the path with every request.

**How Hookdeck Can Help:** Hookdeck keeps the full request path with every event, and its filters can route each path to a different destination.

### Delivery rules aren't on the integration pages

**The Problem:** You don't know how long Deliverect waits for your `200` or whether it retries.

**Why It Happens:** The flow diagrams expect a `200 OK` for every call, but the pages describing them don't state a timeout or retry policy.

**Workarounds:**

* Answer quickly and keep heavy work, such as menu imports, out of the request.
* Use Deliverect's APIs to re-sync orders or menus after an outage on your side.

**How Hookdeck Can Help:** Hookdeck answers Deliverect at once and retries your service on its own schedule, so the timing of your processing no longer affects what Deliverect sees.

## Best practices

### Verify the exact bytes

Deliverect asks you to capture the raw JSON body exactly as received. Use `express.raw({ type: '*/*' })` in Express, `await request.arrayBuffer()` in Next.js and `await request.body()` in FastAPI, and never re-serialise before checking.

### Return `200` for every verified call

Every call in Deliverect's flows expects a `200 OK`, including operational ones you don't act on. Store the request and process it afterwards, as described in [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

### Make status updates idempotent

Order status calls can repeat. Store the order ID and status you have applied, and ignore an update that matches it. [Implementing webhook idempotency](/webhooks/guides/implement-webhook-idempotency) goes into more detail.

### Handle activation and deactivation

The `/register` endpoint is called again with `status=active` and `status=inactive`. Make sure your handler starts and stops accepting orders for that location when it sees them.

## Conclusion

Deliverect's webhooks are calls to the URLs your integration registers, one per purpose, signed with a hex HMAC-SHA256 of the body. Route by URL, accept signed `GET` requests with an empty body, use `channelLink` or `locationId` as the key only in staging, and switch to the production secret from Integration settings once you are certified.

[Hookdeck Event Gateway](https://hookdeck.com) verifies each Deliverect call, keeps track of which URL it came in on, and holds it until your service has processed it.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Deliverect webhooks reliably in minutes.