Agent skill
Deliverect Webhooks Skill
Receive and verify Deliverect webhooks. Use when setting up an endpoint for a Deliverect channel, POS, dispatch or retail integration, verifying the x-server-authorization-hmac-sha256 header, handling order status, menu, snooze or busy-mode calls, or debugging HMAC signature failures and GET requests with no body.
Install this skill
npx skills add hookdeck/webhook-skills --skill 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-sha256header? - 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), so any other method the sender uses (GET, PUT, PATCH, DELETE) must also be allowed on the source.
Verification (core)
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
401for a missing, empty or malformed header or a mismatch;200once handled. A verified request with an empty body is acknowledged with200. - Accept
GET,POST,PUT,PATCHandDELETEon the route and verify first for every method. In Express read the body withexpress.raw({ type: '*/*' }); in Next.js userequest.arrayBuffer(); in FastAPI useawait request.body().
For complete handlers with tests, see examples/express/, examples/nextjs/, 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.
| 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
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):
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 - What Deliverect webhooks are, methods and webhook kinds
- references/setup.md - Secrets, registering URLs, allowing methods on the Hookdeck source
- references/verification.md - Signature details, gotchas, debugging 401s
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests