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-Signatureheader? - 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), thenhmac.compare_digeston 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
200as 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
- references/overview.md - What Delivereasy webhooks are and what they carry
- references/setup.md - Get your API key and register the URL
- references/verification.md - Signature details and debugging
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests