# Guide to Delivereasy Webhooks: Features and Best Practices

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

| Feature | Details |
| --- | --- |
| Configuration | Set by a Delivereasy representative, one URL for staging and one for production |
| Trigger | A booking moves to another stage |
| Signature | base64 HMAC-SHA256 |
| Signature header | `x-signature` |
| Signed content | The raw request body |
| Key | Your Lastmile API key, the value you send as `X-DELIVEREASY-API-KEY` |
| Body | JSON booking resource, in your account's API version |
| Event routing | None; read `status` |
| Response | `200` as soon as the webhook arrives |
| Delivery | At 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:

| Stage | Values |
| --- | --- |
| Waiting for a driver | `not_assigned`, `assigned` |
| Going to pickup | `pickup_enroute`, `pickup_arriving`, `pickup_nearby`, `pickup_arrived`, `pickup_complete` |
| Going to drop-off | `dropoff_enroute`, `dropoff_arrived`, `dropoff_complete` |
| Ended early | `cancelled`, `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](/docs/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](https://developer.delivereasy.co.nz/intro/webhooks) has the reference code.

```javascript
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:

```javascript
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](/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](/webhooks/guides/implement-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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

## 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](https://hookdeck.com) verifies Lastmile signatures for you and keeps each booking update until your tracking service has handled it.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Delivereasy webhooks reliably in minutes.