# 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.

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/delivereasy-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/delivereasy-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/delivereasy-webhooks/examples/fastapi/).

## Payload and Delivery

```json
{ "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

```bash
DELIVEREASY_WEBHOOK_SECRET=your_delivereasy_api_key   # the Lastmile account's API key

```

## Local Development

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

```

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

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/delivereasy-webhooks/references/overview.md) - What Delivereasy webhooks are and what they carry
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/delivereasy-webhooks/references/setup.md) - Get your API key and register the URL
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/delivereasy-webhooks/references/verification.md) - Signature details and debugging
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/delivereasy-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests