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-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), 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 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/, examples/nextjs/, examples/fastapi/.

Which Secret?

EnvironmentSecret
Staging, before certificationThe call's channelLink (present in most calls to partner endpoints), or locationId for Dispatch API integrations and the POS Get Products webhook
Production, certified partnerThe 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 asTypical purpose
order_status_updatestatusUpdateURLOrder status changes
menu_updatemenuUpdateURLMenu publish/update
snooze_unsnoozesnoozeUnsnoozeURLItems snoozed or unsnoozed
busy_modebusyModeURLLocation 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →