Webhooks
Webhooks
When something happens at your branches we post a signed HTTPS request to your address. Verify the signature, answer fast, skip duplicates.
The flow#
- Let's PizzaSomething happened (new order, status, branch closed…)
- Let's Pizza → Your endpointA signed POST
X-LP-Signature: v1=… - Your endpointVerify, store, skip repeats
- Your endpoint → Let's Pizza2xx within 10 seconds
Events#
Orders
| Event | Sent when | data |
|---|---|---|
order.created | A new order reached the branch: at once for cash, after the provider confirms an online payment. | { order } |
order.accepted | The order was accepted. | { order, previousStatus } |
order.preparing | The kitchen started the order. | { order, previousStatus } |
order.ready | The order is ready for pickup or for the rider. | { order, previousStatus } |
order.out_for_delivery | The order left with the rider. | { order, previousStatus } |
order.delivered | The order was delivered. | { order, previousStatus } |
order.picked_up | The customer collected the order at the branch. | { order, previousStatus } |
order.cancelled | The order was cancelled. | { order, previousStatus } |
order.rejected | The branch rejected the order. | { order, previousStatus } |
order.failed_delivery | The order could not be delivered. | { order, previousStatus } |
order.not_collected | The customer did not collect the order. | { order, previousStatus } |
order.ack_overdue | A partner did not acknowledge an order by its deadline (settings.orders.ackMinutes). | { order, previousStatus } |
Payments
| Event | Sent when | data |
|---|---|---|
payment.succeeded | An order reached the branch already paid: online, or at the counter. | { orderId, number, method, tender, amount, paidAt, order } |
payment.refunded | A refund settled, with its credit note when the order had an invoice. | { orderId, number, refundId, amount, reason, method, settledAt, creditNote } |
Invoices
| Event | Sent when | data |
|---|---|---|
invoice.issued | The simplified invoice was issued on delivery or pickup. | { invoice, orderId, number } |
Branches and availability
| Event | Sent when | data |
|---|---|---|
branch.closed | Staff closed the branch for now. | { branch, reason, closedAt } |
branch.opened | Staff reopened the branch. | { branch, openedAt } |
branch.busy | Busy mode started, changed or was ended early. | { branch, busy } |
catalog.published | A new menu version was published from the menu sent by the menu-source partner. | { versionId, source, partner, changes } |
availability.changed | An item or option was switched off or back on at a branch. | { branch, changes } |
ping — A test event sent from the console. { subscriptionId, name, message }
A branch's own hours are not events: nothing is sent when it opens or closes by its hours. Amounts are in halalas; order has the same shape as in the orders guide.
The request#
POST /your/webhook/path HTTP/1.1
Content-Type: application/json
User-Agent: LetsPizza-Webhooks/1
X-LP-Event: order.created
X-LP-Event-Id: 1042.order.created
X-LP-Delivery: 6f3c…
X-LP-Timestamp: 1793350800
X-LP-Signature: v1=eb6ec0ce9e4bd651792cdc8959da458b7490bf8001544013bb22edd1c55afb46| Header | Meaning |
|---|---|
X-LP-Event | The event type. |
X-LP-Event-Id | The event id, the same on every retry: deduplicate on it. |
X-LP-Delivery | This delivery’s id; a replay gets a new one. |
X-LP-Timestamp | When this attempt was signed, in Unix seconds. |
X-LP-Signature | v1= then 64 hex characters. |
The envelope#
{
"version": 1,
"id": "1042.order.created",
"type": "order.created",
"occurredAt": "2026-10-30T09:00:00.000Z",
"branchId": "28",
"data": {
"order": {
"…": "Order"
}
}
}versionis 1. Fields may be added within it; anything else comes as version 2, announced.idis the same on every retry and replay of that event.occurredAtis when the event happened, not when it was sent.branchIdis the branch id; null for ping.
Verifying the signature#
- Take the raw body bytes exactly as received, before any JSON parsing.
- Compute HMAC-SHA256 with the subscription secret (the whole
whsec_…string, as UTF-8 bytes, not base64-decoded) over<timestamp>.<raw body>. - Write it as lowercase hex, prefixed
v1=, and compare with the header in constant time. The header may carry several comma-separated values in the future: accept if any matches. - Refuse it when the timestamp is more than 300 seconds from your clock (keep it on NTP); answer 401 when it does not verify.
import crypto from 'node:crypto';
/**
* rawBody: the body exactly as received (a Buffer), before any JSON parsing.
* With Express: app.post('/lp-webhooks', express.raw({ type: 'application/json' }), handler)
*/
export function verifyLpSignature({ secret, timestamp, rawBody, signatureHeader, toleranceSeconds = 300 }) {
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (!Number.isFinite(age) || age > toleranceSeconds) return false;
const mac = crypto.createHmac('sha256', Buffer.from(secret, 'utf8'));
mac.update(`${timestamp}.`, 'utf8');
mac.update(rawBody);
const expected = Buffer.from('v1=' + mac.digest('hex'));
return String(signatureHeader ?? '')
.split(',')
.map((s) => Buffer.from(s.trim()))
.some((candidate) => candidate.length === expected.length && crypto.timingSafeEqual(candidate, expected));
}Test vector#
Run your code on these values: it must produce the same signature. (Skip the clock check here: the timestamp is old on purpose.)
| Input | Value |
|---|---|
| secret | whsec_test_vector_not_a_real_secret_0123456789 |
X-LP-Timestamp | 1793350800 |
| raw body | {"version":1,"id":"1042.order.created","type":"order.created","occurredAt":"2026-10-30T09:00:00.000Z","branchId":"28","data":{}} |
X-LP-Signature | v1=eb6ec0ce9e4bd651792cdc8959da458b7490bf8001544013bb22edd1c55afb46 |
printf '%s' '1793350800.{"version":1,"id":"1042.order.created","type":"order.created","occurredAt":"2026-10-30T09:00:00.000Z","branchId":"28","data":{}}' \
| openssl dgst -sha256 -hmac 'whsec_test_vector_not_a_real_secret_0123456789'
# expected hex: eb6ec0ce9e4bd651792cdc8959da458b7490bf8001544013bb22edd1c55afb46Retries#
| Attempt | When |
|---|---|
| 1 | Within seconds of the event |
| 2 | 1 minute after the previous attempt failed |
| 3 | 5 minutes after the previous attempt failed |
| 4 | 30 minutes after the previous attempt failed |
| 5 | 2 hours after the previous attempt failed |
| 6 (last) | 12 hours after the previous attempt failed |
- After 6 failed attempts the delivery is dead; it stays in the log for 30 days and can be replayed.
- 50 failed attempts in a row pause the subscription: events are kept, not sent, until it is resumed; then they all go out.
- Deliveries are not ordered: use occurredAt and the order’s status and history, and treat an older status arriving after a newer one as stale.
Replay and deduplication#
Delivery is at least once: a timeout after you processed an event looks like a failure to us and is retried. A replay from the console sends the same envelope (same id), with a new X-LP-Delivery.
// inside your handler, after verifyLpSignature(...)
const event = JSON.parse(rawBody);
const firstTime = await db.processedEvents.insertIfAbsent(event.id); // unique key on id
if (!firstTime) return res.sendStatus(204); // a repeat: already handled
res.sendStatus(204); // answer first…
await queue.add(event); // …work afterYour own subscriptions#
With the webhooks:manage scope you manage your subscriptions yourself through /partner/v1/webhooks: address and events, the delivery log, replay, a test event and a new secret. The branches are your key’s, and you receive only what is yours:
| Events | Scope needed | What you get |
|---|---|---|
order.* · invoice.issued | orders:read | Only the orders that are in your feed. |
payment.* | payments:read | Payments of your orders. |
catalog.published | catalog:read | Each new menu version published. |
branch.* · availability.changed | branches:read | Your key’s branches. |
order.ack_overdue | orders:read | Only about yourself: an order you did not acknowledge in time. |
Customer details travel whole or trimmed according to your settings.customerData as Let’s Pizza sets it now, not by the subscription request. The signing secret is shown once, at creation; if lost, rotate it.
Personal data#
By default customer data is trimmed: first name, a masked phone, no address. Full data is switched on for a given subscription only when truly needed (a delivery fleet, say), and switching it on is audited.
Address rules#
In production the address must be https://, carry no user name or password, and resolve to a public address: private and local addresses are refused, checked again at every connection.