Let's Pizza Developersv1.0.0

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#

  1. Let's PizzaSomething happened (new order, status, branch closed…)
  2. Let's Pizza → Your endpointA signed POSTX-LP-Signature: v1=…
  3. Your endpointVerify, store, skip repeats
  4. Your endpoint → Let's Pizza2xx within 10 seconds

Events#

Orders

EventSent whendata
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

EventSent whendata
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

EventSent whendata
invoice.issued The simplified invoice was issued on delivery or pickup.{ invoice, orderId, number }

Branches and availability

EventSent whendata
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#

HTTP
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
HeaderMeaning
X-LP-EventThe event type.
X-LP-Event-IdThe event id, the same on every retry: deduplicate on it.
X-LP-DeliveryThis delivery’s id; a replay gets a new one.
X-LP-TimestampWhen this attempt was signed, in Unix seconds.
X-LP-Signaturev1= then 64 hex characters.

The envelope#

JSON
{
  "version": 1,
  "id": "1042.order.created",
  "type": "order.created",
  "occurredAt": "2026-10-30T09:00:00.000Z",
  "branchId": "28",
  "data": {
    "order": {
      "…": "Order"
    }
  }
}
  • version is 1. Fields may be added within it; anything else comes as version 2, announced.
  • id is the same on every retry and replay of that event.
  • occurredAt is when the event happened, not when it was sent.
  • branchId is the branch id; null for ping.

Verifying the signature#

  1. Take the raw body bytes exactly as received, before any JSON parsing.
  2. Compute HMAC-SHA256 with the subscription secret (the whole whsec_… string, as UTF-8 bytes, not base64-decoded) over <timestamp>.<raw body>.
  3. 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.
  4. 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.)

InputValue
secretwhsec_test_vector_not_a_real_secret_0123456789
X-LP-Timestamp1793350800
raw body{"version":1,"id":"1042.order.created","type":"order.created","occurredAt":"2026-10-30T09:00:00.000Z","branchId":"28","data":{}}
X-LP-Signaturev1=eb6ec0ce9e4bd651792cdc8959da458b7490bf8001544013bb22edd1c55afb46
openssl
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: eb6ec0ce9e4bd651792cdc8959da458b7490bf8001544013bb22edd1c55afb46

Retries#

AttemptWhen
1Within seconds of the event
21 minute after the previous attempt failed
35 minutes after the previous attempt failed
430 minutes after the previous attempt failed
52 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.

Node.js
// 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 after

Your 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:

EventsScope neededWhat you get
order.* · invoice.issuedorders:readOnly the orders that are in your feed.
payment.*payments:readPayments of your orders.
catalog.publishedcatalog:readEach new menu version published.
branch.* · availability.changedbranches:readYour key’s branches.
order.ack_overdueorders:readOnly 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.