Big restaurant chains on Tiffin don't want to watch a kitchen tablet. They want new orders to appear in their own point-of-sale (POS) system, next to their dine-in orders. They could poll Tiffin's API every few seconds asking "anything new?", but with 2,000 outlets polling every 5 seconds, that's 400 requests a second, almost all of them answered with "no".
The better answer is to flip it around: when an order is placed, Tiffin calls them. That's a webhook. It sounds trivial: just make an HTTP request. Doing it reliably and safely, to thousands of servers you don't control, is not.
Quick recap. This lesson builds on Module 7 (queues, workers, retries and jobs that can safely run twice), Module 12 ("Idempotency keys" and "Retries and backoff") and Module 15 ("The outbox pattern"). You don't need them in detail, but the ideas come back here.
What a webhook is
A webhook is an HTTP request your system sends to a URL someone else registered, to tell them an event happened.
It's an API call in reverse. Normally the customer's system calls you. With a webhook, you call the customer's system, at a URL they gave you, with a body you define.
A Tiffin webhook to a restaurant chain might look like this:
POST /tiffin/webhooks HTTP/1.1
Host: pos.saffronkitchen.example
Content-Type: application/json
Tiffin-Event-Id: evt_01J9ZK3Q7M
Tiffin-Timestamp: 1792351200
Tiffin-Signature: v1=5f2b9c...e81a
{
"id": "evt_01J9ZK3Q7M",
"type": "order.placed",
"created_at": "2026-10-18T19:20:00Z",
"data": { "order_id": 812, "outlet_id": 77, "total": 64000 }
}
You'll almost certainly be on both sides of webhooks. Tiffin receives them from its payment provider ("payment succeeded") and sends them to restaurant chains ("order placed"). Each side has its own rules.