API Reference
Webhooks

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

RouteWhat it does
GET /v1/webhooksList endpoints
POST /v1/webhooksCreate an endpoint. Returns the signing secret once.
GET /v1/webhooks/:idOne endpoint
PATCH /v1/webhooks/:idChange name, url, events or enabled
DELETE /v1/webhooks/:idDelete an endpoint
POST /v1/webhooks/:id/rotate-secretIssue 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/testSend a webhook.test event now and return the result. 5 per minute per endpoint.
GET /v1/webhooks/:id/deliveriesDelivery history, paginated (page, pageSize, status, eventType, includeTests, from, to)
GET /v1/webhooks/deliveries/:idOne delivery, with the payload and the response your server gave
POST /v1/webhooks/deliveries/:id/redeliverQueue 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

EventSent when
order.createdAn order is placed: at the till, from a guest's phone, or as a booking's pre-order
order.updatedAn 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.completedAn order is paid in full, at the till or online (fires once)
order.cancelledAn order is voided or a QR order is rejected (voidReason set)
payment.succeededOnline: the gateway confirmed a payment. In person (source: "in_person"): the bill was marked paid at the till or at the door
payment.failedAn online payment is declined or fails at the gateway
payment.refundedAn online refund completes or is recorded by hand, or a paid order is voided and its money handed back at the till
reservation.createdA reservation is made
reservation.updatedA reservation is edited (time, party size, table, notes), seated, completed, marked no-show, or reopened
reservation.confirmedA reservation is confirmed
reservation.cancelledA reservation is cancelled
delivery.assignedA rider is assigned to a delivery
delivery.picked_upThe rider collects the order
delivery.deliveredThe order is delivered
menu.item.createdA menu item is created
menu.item.updatedA menu item is changed, including its availability
menu.item.deletedA menu item is deleted (deleted: true, the item as it was)
customer.createdA new customer record is created
inventory.lowstockAn ingredient's stock crosses its reorder point, from above to at or below (data: ingredientId, name, onHand, reorderPoint)
webhook.testYou 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": { }
}
FieldMeaning
idThe 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.
apiVersion2026-11-10. Fields are only ever added under one version; a rename or removal would come with a new version.
typeThe event.
createdAtWhen the event happened.
restaurantIdThe location the event belongs to.
deliveryIdThis one delivery, also X-Tahlib-Delivery. Differs per endpoint and per redelivery.
dataThe 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:

FieldMeaning
id, numberTahlib's id, and the per-restaurant number printed on receipts
statuspending (QR order waiting for staff) · awaiting_payment (online checkout not paid yet) · open · held · sent (in the kitchen) · ready · served · paid · voided
channelqr · pos · phone
serviceModedinein · takeaway · delivery
tableId, tableThe table and its printed code; null off the floor
reservationIdThe booking a pre-order belongs to
customerId, guestName, guestPhoneWho ordered, when known. Phone is E.164.
notesThe order-level note
deliveryDelivery 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, totalThe bill. Tips are never in total.
tipTotal, paidOnline, paidGiftCardTips on top of total; the parts already paid online and by gift card
paymentMethodCodeHow it was settled once paid (cash, card, …; online when paid online)
currencyCode, createdAt, updatedAt, placedAt … voidedAt, voidReasonCurrency 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:

  1. Read the raw body before any JSON parsing. Re-serialising the parsed JSON can change the bytes and break the signature.
  2. Split X-Tahlib-Signature on , and take t and every v1. After a secret rotation the header carries two, one per secret (t=…,v1=<new>,v1=<old>), until the old secret's grace period ends.
  3. Reject the request if t is more than 5 minutes from your clock. This stops replays.
  4. Compute the HMAC above and compare it to each v1 in 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:

InputValue
secretsuper-secret-string
body (exact bytes){"id":"evt_1","type":"webhook.test","data":{"hello":"world"}}
timestamp1700000000
expected headert=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": "…" }.

previousSecretValidHoursEffect
24 (default) or 72For 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.
0The 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 with PATCH /v1/webhooks/:id and { "enabled": true }, which also clears the count.
  • A redelivery sends the same event again as a new delivery: new deliveryId, same event id.
  • A delivery's status is one of pending, in_flight, retrying, succeeded or failed. 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: webhookEnvelope in apps/api/src/modules/webhooks/webhook-delivery.service.ts; rotation: rotateSecret in webhooks.service.ts
  • Where each event is sent: webhooks.publish(…) calls in apps/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 by apps/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