Agent skill

Delivereasy Webhooks Skill

Receive and verify Delivereasy Lastmile webhooks. Use when setting up an endpoint for Delivereasy booking updates, verifying the X-Signature header (base64 HMAC-SHA256 of the raw body, keyed with your API key), debugging 401 signature failures, or handling booking status changes.

Install this skill

npx skills add hookdeck/webhook-skills --skill delivereasy-webhooks


Delivereasy (delivereasy.co.nz) is a New Zealand food delivery and last-mile courier company. Lastmile API partners get a webhook each time a booking changes stage. Every delivery is the booking resource itself (id, booking_identifier, status, driver, pickup, dropoff, ...). There is no event-name field or header, so dispatch on status.

Only Lastmile webhooks are supported: paste your Delivereasy API key. Marketplace webhooks (X-Delivereasy-Signature) aren't covered.

When to Use This Skill

  • How do I receive Delivereasy webhooks?
  • How do I verify the Delivereasy X-Signature header?
  • Why does my Delivereasy webhook endpoint return 401?
  • How do I handle Delivereasy Lastmile booking status changes?

Verification (core)

The X-Signature header is the bare, padded, standard base64 of HMAC-SHA256 over the raw request body bytes, keyed with your Delivereasy API key (used as UTF-8 bytes; there is no separate webhook secret). Nothing else is signed: no timestamp, id or header.

const crypto = require('crypto');

function verifyDelivereasy(rawBody, signature, apiKey) {   // rawBody: Buffer
  if (!apiKey || typeof signature !== 'string') return false;
  if (!/^[A-Za-z0-9+/]{43}=$/.test(signature)) return false;   // exact 44-char padded base64
  const expected = crypto.createHmac('sha256', apiKey).update(rawBody).digest('base64');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); // equal length
}
  • Header: X-Signature. Compare the whole value as one digest: no prefix, no list.
  • Validate the format first, then compare the base64 strings in constant time. Decoding alone is not enough: a value with stray low bits in its last character decodes to the same bytes but must be rejected. Never call Buffer.from(sig, 'base64') on an unvalidated value.
  • Python: re.fullmatch(r"[A-Za-z0-9+/]{43}=", sig), then hmac.compare_digest on bytes.
  • Missing, empty, malformed or mismatched header: respond 401. There is no signed timestamp, so don't invent a replay window.
  • Read the body raw (express.raw({ type: '*/*' }), await request.arrayBuffer(), await request.body()) and parse JSON only after the check.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Payload and Delivery

{ "id": 12345, "booking_identifier": "ABC123", "status": "...", "driver": {}, "pickup": {}, "dropoff": {} }
  • Method: POST.
  • Return 200 as soon as the webhook arrives and process asynchronously.
  • Delivery is at least once: deduplicate on the booking id.
  • The retry schedule and timeout are not documented.
  • The webhook URL (one for staging, one for production) is set by a Delivereasy representative.

Environment Variables

DELIVEREASY_WEBHOOK_SECRET=your_delivereasy_api_key   # the Lastmile account's API key

Local Development

npx hookdeck-cli listen 3000 delivereasy --path /webhooks/delivereasy

No account required. Give the printed URL to your Delivereasy representative.

Resources


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →