Gareth Wilson Gareth Wilson

Guide to Delivereasy Webhooks: Features and Best Practices

Published


Delivereasy is a New Zealand delivery company that also offers its drivers to other businesses through the Lastmile API: a restaurant or shop books a courier, and a Delivereasy driver collects and delivers the order. Once a booking exists, the partner wants to know where it is. Delivereasy's webhook answers that by sending the whole booking to your server every time it moves to a new stage, from driver assigned through pickup to drop-off.

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

This guide covers the Lastmile booking webhook: how it is set up through Delivereasy, what the booking body contains, how to verify the base64 X-Signature, and how it differs from Delivereasy's Marketplace webhooks.

What are Delivereasy webhooks?

Delivereasy has two partner APIs with their own webhooks. Lastmile is for businesses that book Delivereasy couriers, and sends a booking updated webhook. Marketplace is for platforms that receive Delivereasy food orders, and sends order webhooks with a different body and signature. This guide, and Hookdeck's Delivereasy source, cover Lastmile only.

The Lastmile webhook has no event types. Every delivery is the same notification, and the body is the booking itself, exactly as the Retrieve a booking endpoint returns it. The booking's status tells you which stage it has reached.

Delivereasy signs the body with your API key. There is no separate webhook secret to generate or rotate.

Delivereasy webhook features

FeatureDetails
ConfigurationSet by a Delivereasy representative, one URL for staging and one for production
TriggerA booking moves to another stage
Signaturebase64 HMAC-SHA256
Signature headerx-signature
Signed contentThe raw request body
KeyYour Lastmile API key, the value you send as X-DELIVEREASY-API-KEY
BodyJSON booking resource, in your account's API version
Event routingNone; read status
Response200 as soon as the webhook arrives
DeliveryAt least once; retries and timeout not documented

Events and payloads

Lastmile sends one webhook, and its body is the booking resource itself (booking_response: id, booking_identifier, status, driver, pickup, dropoff, ...), with no event, type or action property; the only documented header is X-Signature. status (not_assigned, assigned, pickup_enroute, ..., dropoff_complete, cancelled, returned) is the booking's stage, not an event type: every delivery is the same booking updated webhook. Route on id / booking_identifier and status.

The full set of status values in the 2025-04-01 API is:

StageValues
Waiting for a drivernot_assigned, assigned
Going to pickuppickup_enroute, pickup_arriving, pickup_nearby, pickup_arrived, pickup_complete
Going to drop-offdropoff_enroute, dropoff_arrived, dropoff_complete
Ended earlycancelled, return_in_progress, returned

The rest of the booking gives you what a tracking page needs. driver has the driver's name, contact_number, profile_image_url and current latitude and longitude. pickup and dropoff include addresses, instructions, requested times and eta_to_pickup_in_seconds or eta_to_dropoff_in_seconds. booking_details carries the fee in cents, the estimated times and a customer_tracking_url. undeliverable_action is leave_at_premise, return_to_pickup or dispose.

Delivereasy publishes the body as a schema without example values, so there is no sample to show here. Capture a staging delivery to see real data.

Setting up Delivereasy webhooks

Lastmile webhooks are not self-serve.

  1. Decide on your endpoint URLs, for example https://staging.example.com/webhooks/delivereasy and https://example.com/webhooks/delivereasy.
  2. Ask your Delivereasy representative to configure them on your account. You get one URL per environment.
  3. Store the matching API key on each environment's server, for example as DELIVEREASY_API_KEY. Staging and production have different keys, and a webhook only verifies against the key of the environment that sent it.
  4. Create a booking in staging to trigger deliveries.

Delivereasy shapes the body to match the API version your account uses, so if you upgrade the API version, expect the webhook body to change at the same time.

With Hookdeck, create a source with the Delivereasy source type, paste the API key as its verification secret, and give your Delivereasy representative the Hookdeck source URL. Use separate sources for staging and production, each with its own key. To see staging deliveries on your laptop, run npx hookdeck-cli listen 3000 delivereasy --path /webhooks/delivereasy with the Hookdeck CLI.

Securing Delivereasy webhooks

Compute an HMAC-SHA256 of the raw body with the API key as the key and compare it with the base64 value in X-Signature. Delivereasy's Ruby example uses Base64.strict_encode64, so the header is padded standard base64. The verifier below decodes the header only if it is canonical base64, then compares bytes in constant time. Delivereasy's webhook page has the reference code.

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

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-signature'];
  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) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

The canonical check matters because Node's base64 decoder is lenient: it skips invalid characters, and a final character with stray low bits decodes to the same bytes as the correct one.

Once verified, the handler reads the booking's status:

const express = require('express');

const app = express();

app.post('/webhooks/delivereasy', express.raw({ type: '*/*' }), async (req, res) => {
  const apiKey = process.env.DELIVEREASY_API_KEY;
  if (!apiKey) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, apiKey)) return res.sendStatus(401);

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

  // Delivereasy asks for a fast 200, so queue the update and let a worker apply it.
  try {
    await queue.add('delivereasy-booking', {
      bookingIdentifier: booking.booking_identifier,
      status: booking.status,
      driver: booking.driver,
      partnerStoreId: booking.partner_store_id,
      bookingId: booking.id,
    });
  } catch {
    return res.sendStatus(503);
  }
  res.sendStatus(200);
});

queue stands for your own job queue. The worker updates order tracking and tells the store when a booking ends as cancelled or returned. If the queue write fails, the handler returns 503 instead of acknowledging a booking it hasn't saved.

Nothing in the signature carries a time, so there is no freshness check to make. Hookdeck's Delivereasy source verifies the same base64 HMAC with your API key. It accepts the request with 200 and then records a verification failure if the signature doesn't match, rather than returning 401 to Delivereasy.

Make Delivereasy webhooks production-ready. Hookdeck Event Gateway verifies the Lastmile X-Signature, stores every booking update, and delivers it to your tracking service with retries you control.

Delivereasy webhook limitations and pain points

The API key is the signing key

The Problem: Rotating your API key also changes webhook signing, and every service that verifies webhooks must hold your API key.

Why It Happens: Delivereasy uses the Lastmile API key as the HMAC key. There is no separate webhook secret.

Workarounds:

  • Keep the API key in one secret store, read by both your API client and your webhook receiver.
  • When you rotate it, update the receiver at the same moment as the API client.

How Hookdeck Can Help: With Hookdeck verifying the signature, only the Hookdeck source needs the API key. Your downstream services receive verified requests and never see it.

No retry schedule

The Problem: You don't know whether a missed stage change will be sent again.

Why It Happens: Delivereasy tells you to return 200 quickly and expect duplicates, but documents no retry schedule or timeout.

Workarounds:

  • Queue the booking and respond with 200 before doing any other work.
  • For bookings that seem stuck, call the Retrieve a booking endpoint for the current state.

How Hookdeck Can Help: Hookdeck responds to Delivereasy immediately and retries your service until it succeeds, so a slow or failing handler doesn't depend on Delivereasy's undocumented behaviour.

Duplicates and no ordering

The Problem: The same stage arrives twice, or pickup_complete arrives after dropoff_enroute.

Why It Happens: Delivereasy says webhooks may arrive more than once. Ordering is not documented, and there is no event or delivery ID.

Workarounds:

  • Deduplicate on id plus status.
  • Rank statuses in lifecycle order and ignore an update that would move a booking backwards, except for the cancellation and return states.

How Hookdeck Can Help: Hookdeck's deduplication can drop a request whose id and status match one already delivered.

Marketplace webhooks are different

The Problem: A Marketplace order webhook fails Lastmile verification.

Why It Happens: Marketplace uses X-Delivereasy-Signature with a hex digest, and its key depends on the API version (the API key on 2026-01-01, a separate webhook secret on 2025-01-01). The body is an order notification, not a booking.

Workarounds:

  • Give Marketplace webhooks their own endpoint and verifier.

How Hookdeck Can Help: Hookdeck's Delivereasy source is for Lastmile. Send Marketplace webhooks to a separate source with its own configuration.

Best practices

Keep environments apart

Staging and production each have one URL and their own API key. Point them at different endpoints or Hookdeck sources so a staging key never has to sit next to a production one.

Verify the raw body

Use express.raw({ type: '*/*' }) in Express, await request.arrayBuffer() in Next.js and await request.body() in FastAPI, and compute the HMAC before parsing anything.

Treat the body as the latest snapshot

Every webhook carries the full booking, so you can overwrite your copy rather than merge changes, as long as you don't let an older status replace a newer one. Our guide to webhook idempotency covers storing the key safely.

Respond first

Delivereasy asks for an immediate 200. Store the booking and process it in the background, as described in why to process webhooks asynchronously.

Conclusion

Delivereasy's Lastmile webhook sends the whole booking on every stage change, signed with a base64 HMAC-SHA256 keyed with your API key. Verify the canonical base64 against the raw body, keep staging and production keys apart, deduplicate on booking id and status, and don't let late updates move a booking backwards.

Hookdeck Event Gateway verifies Lastmile signatures for you and keeps each booking update until your tracking service has handled it.

Get started with Hookdeck for free and handle Delivereasy webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.