Webhooks
Tahlib can POST a signed JSON message to your HTTPS endpoint when something happens at a restaurant: an order is placed, a payment succeeds, a delivery is picked up.
Building a receiver? Start with the integration guide: it has working receivers in PHP, Laravel, Node.js and Python, test vectors and a go-live checklist. This page is the reference.
Product: Advanced API & Webhooks (module key webhooks). Without it
every /v1/webhooks route returns 402.
Managing endpoints
| Route | What it does |
|---|---|
GET /v1/webhooks | List endpoints |
POST /v1/webhooks | Create an endpoint. Returns the signing secret once. |
GET /v1/webhooks/:id | One endpoint |
PATCH /v1/webhooks/:id | Change name, url, events or enabled |
DELETE /v1/webhooks/:id | Delete an endpoint |
POST /v1/webhooks/:id/rotate-secret | Issue a new signing secret. Returns it once. Optional { "previousSecretValidHours": 0 | 24 | 72 } (default 24) keeps the old one signing too; see Rotating the secret. |
POST /v1/webhooks/:id/test | Send a webhook.test event now and return the result. 5 per minute per endpoint. |
GET /v1/webhooks/:id/deliveries | Delivery history, paginated (page, pageSize, status, eventType, includeTests, from, to) |
GET /v1/webhooks/deliveries/:id | One delivery, with the payload and the response your server gave |
POST /v1/webhooks/deliveries/:id/redeliver | Queue the same payload again as a new delivery |
Reading needs the settings.view permission. Every change needs
settings.edit and the restaurant's owner role; anyone else gets 403.
Create an endpoint:
{
"name": "Order sync",
"url": "https://example.com/tahlib/webhooks",
"events": ["order.created", "order.completed"]
}The response is { "endpoint": { … }, "secret": "…" }. Store the secret:
Tahlib keeps a hash of it and an encrypted copy to sign with, and cannot show
it again. If you lose it, rotate.
The URL must use https://. Plain http:// is accepted only for
localhost, 127.0.0.1 and [::1], for local testing against a local API.
The production API does not deliver to private or internal addresses.
Events
| Event | Sent when |
|---|---|
order.created | An order is placed: at the till, from a guest's phone, or as a booking's pre-order |
order.updated | An order changes: accepted, sent to the kitchen, ready, served, items added to an open check, a pre-order released when the guest is seated |
order.completed | An order is paid in full, at the till or online (fires once) |
order.cancelled | An order is voided or a QR order is rejected (voidReason set) |
payment.succeeded | Online: the gateway confirmed a payment. In person (source: "in_person"): the bill was marked paid at the till or at the door |
payment.failed | An online payment is declined or fails at the gateway |
payment.refunded | An online refund completes or is recorded by hand, or a paid order is voided and its money handed back at the till |
reservation.created | A reservation is made |
reservation.updated | A reservation is edited (time, party size, table, notes), seated, completed, marked no-show, or reopened |
reservation.confirmed | A reservation is confirmed |
reservation.cancelled | A reservation is cancelled |
delivery.assigned | A rider is assigned to a delivery |
delivery.picked_up | The rider collects the order |
delivery.delivered | The order is delivered |
menu.item.created | A menu item is created |
menu.item.updated | A menu item is changed, including its availability |
menu.item.deleted | A menu item is deleted (deleted: true, the item as it was) |
customer.created | A new customer record is created |
inventory.lowstock | An ingredient's stock crosses its reorder point, from above to at or below (data: ingredientId, name, onHand, reorderPoint) |
webhook.test | You choose Send test or call the test route |
The request
POST /tahlib/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: Tahlib-Webhooks/1.0
X-Tahlib-Event: order.created
X-Tahlib-Event-Id: 5f1a3c5e-7b9d-4f1a-8c3e-5a7c9e1b3d57
X-Tahlib-Api-Version: 2026-11-10
X-Tahlib-Delivery: 11111111-2222-3333-4444-555555555555
X-Tahlib-Endpoint: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
X-Tahlib-Timestamp: 1700000000
X-Tahlib-Body-SHA256: <sha256 hex of the body>
X-Tahlib-Signature: t=1700000000,v1=<hmac_sha256 hex>The body is always this envelope:
{
"id": "5f1a3c5e-7b9d-4f1a-8c3e-5a7c9e1b3d57",
"apiVersion": "2026-11-10",
"type": "order.created",
"createdAt": "2026-11-10T08:00:00.000Z",
"restaurantId": "ffffffff-aaaa-bbbb-cccc-dddddddddddd",
"deliveryId": "11111111-2222-3333-4444-555555555555",
"data": { }
}| Field | Meaning |
|---|---|
id | The event id, also X-Tahlib-Event-Id. The same on every endpoint that receives the event, on every retry and on a redelivery. Deduplicate on it. |
apiVersion | 2026-11-10. Fields are only ever added under one version; a rename or removal would come with a new version. |
type | The event. |
createdAt | When the event happened. |
restaurantId | The location the event belongs to. |
deliveryId | This one delivery, also X-Tahlib-Delivery. Differs per endpoint and per redelivery. |
data | The event's payload. |
Duplicates and order. You can receive an event twice (your server
answered late, or the owner pressed Redeliver): skip an id you have already
processed. Delivery order is not guaranteed: every resource carries
updatedAt, so keep the snapshot with the newest one. Each event carries
the whole resource, so the newest snapshot is all you need.
Money. Amounts are integers in the minor unit of currencyCode. AED, SAR
and INR have two decimals; KWD and OMR have three, so 1500 is KWD 1.500.
For the order.* events, data is the whole order as it stands after the
change, every line included, so any one of them is enough to create or update
the ticket on your side:
| Field | Meaning |
|---|---|
id, number | Tahlib's id, and the per-restaurant number printed on receipts |
status | pending (QR order waiting for staff) · awaiting_payment (online checkout not paid yet) · open · held · sent (in the kitchen) · ready · served · paid · voided |
channel | qr · pos · phone |
serviceMode | dinein · takeaway · delivery |
tableId, table | The table and its printed code; null off the floor |
reservationId | The booking a pre-order belongs to |
customerId, guestName, guestPhone | Who ordered, when known. Phone is E.164. |
notes | The order-level note |
delivery | Delivery orders only: address, lat/lng, distanceM, payOnDeliveryMethod, cashChangeFor |
items[] | Every line: name/nameAr (size included), quantity, unitPrice, modifiers[] (name/nameAr/priceDelta), notes, lineSubtotal/lineTax/lineTotal, kitchenStatus, station |
subtotal, discountTotal, tierDiscount, deliveryFee, serviceCharge, taxTotal, total | The bill. Tips are never in total. |
tipTotal, paidOnline, paidGiftCard | Tips on top of total; the parts already paid online and by gift card |
paymentMethodCode | How it was settled once paid (cash, card, …; online when paid online) |
currencyCode, createdAt, updatedAt, placedAt … voidedAt, voidReason | Currency and lifecycle timestamps. Keep the newest updatedAt. |
Payment events carry the payment with source (online or in_person) and
the order; delivery events carry the delivery and the order. The same order
shape is returned by the read API (GET /v1/integration/orders/:id, see the
guide).
Verifying the signature
The signature is an HMAC-SHA256, keyed with your endpoint's secret, over the timestamp, a dot, and the exact request body:
v1 = hex( HMAC_SHA256( secret, "<t>." + rawBody ) )The secret is used exactly as shown, as text; don't base64-decode it.
To verify a request:
- Read the raw body before any JSON parsing. Re-serialising the parsed JSON can change the bytes and break the signature.
- Split
X-Tahlib-Signatureon,and taketand everyv1. After a secret rotation the header carries two, one per secret (t=…,v1=<new>,v1=<old>), until the old secret's grace period ends. - Reject the request if
tis more than 5 minutes from your clock. This stops replays. - Compute the HMAC above and compare it to each
v1in constant time. Accept the request when any of them matches.
Node.js:
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyTahlibSignature(rawBody: string | Buffer, header: string, secret: string): boolean {
const parts = header.split(',').map((p) => p.trim());
const t = parts.find((p) => p.startsWith('t='))?.slice(2);
const signatures = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3));
if (!secret || !t || !/^\d+$/.test(t) || signatures.length === 0) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
return signatures.some((s) => {
const given = Buffer.from(s, 'hex');
return given.length === expected.length && timingSafeEqual(given, expected);
});
}The same check in PHP, Laravel and Python, inside complete receivers, is in the integration guide.
X-Tahlib-Body-SHA256 is the SHA-256 of the body. It lets a receiver behind
a proxy that re-parses JSON check the body's integrity. It is not a
signature: always verify X-Tahlib-Signature.
Test vector
Check your implementation against this before going live:
| Input | Value |
|---|---|
| secret | super-secret-string |
| body (exact bytes) | {"id":"evt_1","type":"webhook.test","data":{"hello":"world"}} |
| timestamp | 1700000000 |
| expected header | t=1700000000,v1=b0b97e3addf7c105c1b0d8329df7d3ea972123f442cc12665760768a64510744 |
During a rotation, with old-secret-string as the previous secret, the same
body and timestamp give
t=1700000000,v1=b0b97e3addf7c105c1b0d8329df7d3ea972123f442cc12665760768a64510744,v1=87b7100815b1a522059553ad1560d546d27f85f37bde7ab4f6e9ea52de82cbf8,
which must verify with either secret. Both vectors are years old, so switch
the 5-minute check off when you run them.
Rotating the secret
POST /v1/webhooks/:id/rotate-secret, or Rotate secret on the endpoint
page, issues a new secret and returns it once:
{ "endpoint": { … }, "secret": "…" }.
previousSecretValidHours | Effect |
|---|---|
24 (default) or 72 | For that long every delivery is signed with both secrets, new first. A receiver holding either keeps verifying, so you can deploy the new secret at your own pace. endpoint.previousSecretExpiresAt says when the old one stops. |
0 | The old secret stops at once. Deliveries fail until your receiver has the new one, and are retried. |
Endpoints created before 10 November 2026 kept their secret only in Redis. If that copy was lost, deliveries fail with "signing secret unavailable" until you rotate.
Delivery and retries
- Return any 2xx within 10 seconds to acknowledge. Anything else, including a redirect, counts as a failure. Redirects are not followed.
- A failed delivery is retried 10 seconds, 30 seconds, 5 minutes, 30 minutes
and 2 hours after each failure: six attempts in all. After the sixth it
is marked
failed. - After 5 deliveries in a row end as
failed, the endpoint is disabled, its owners get a push notification, and the endpoint shows the reason. A successful delivery resets the count, and test deliveries don't count. Re-enable an endpoint withPATCH /v1/webhooks/:idand{ "enabled": true }, which also clears the count. - A redelivery sends the same event again as a new delivery: new
deliveryId, same eventid. - A delivery's
statusis one ofpending,in_flight,retrying,succeededorfailed. The first 4 KB of your response body is stored with it.
Not part of this API
GET and POST /v1/webhooks/whatsapp are Tahlib's own receiver for the
Meta WhatsApp Cloud API. Integrators don't call them.
Sources
- Routes and owner check:
apps/api/src/modules/webhooks/webhooks.controller.ts,webhooks.service.ts - Event list, URL rule, envelope, rotation windows and delivery types:
packages/shared-types/src/webhook.ts - Envelope as sent:
webhookEnvelopeinapps/api/src/modules/webhooks/webhook-delivery.service.ts; rotation:rotateSecretinwebhooks.service.ts - Where each event is sent:
webhooks.publish(…)calls inapps/api/src/modules/{orders,payments,reservations,dispatch,menu,crm,inventory}/ - Payloads:
apps/api/src/modules/webhooks/payloads.ts; contract and an example of every event:docs/runbooks/webhooks-events.md, checked key for key byapps/api/test/webhook-payloads.e2e-spec.ts - Headers, timeout, retries, auto-disable:
apps/api/src/modules/webhooks/webhook-delivery.service.ts; redirects:webhook-http.ts - Signing:
apps/api/src/modules/webhooks/webhook-signing.ts; test vector:apps/api/test/webhook-signing.e2e-spec.ts - WhatsApp receiver:
docs/integrations/whatsapp-cloud-api.md