Webhooks: The API Calls Back

Vera writes to Jonas about the forty polls, half expecting to be told to live with it. His reply offers something else: give Tandem an address of your own, he says, and the moment ride rd_7c29 ends, Tandem will send the news to you. One message, seconds after the wheels stop, with no asking at all.

That arrangement is called a webhook: an address you register with a provider, which the provider sends a message to when something happens. It is the whole of this page, and it quietly complicates the rule Chapter 1 fixed in place — the one that said the server never calls first.

The Deal

The arrangement has two halves and both are set up once. Vera gives Tandem a URL in the partner settings — call it https://reports.riverport.example/tandem-events — and chooses which happenings she wants to hear about. Tandem's side of the deal is that whenever one of those happens, it sends an HTTP request to that address carrying the news.

An event is the name for one such happening: a thing that occurred at a moment in time. Tandem publishes a list of the ones it will announce, and each has a name in the same style — ride.completed, ride.started, station.offline. Vera subscribes to ride.completed and stops polling.

The everyday version is the slip the postal service leaves in your letterbox. Instead of walking to the depot every hour to ask whether your parcel arrived, the slip lands when it actually does, and then you make one purposeful trip. The slip is deliberately small: it is a notification, not the goods. Hold on to that distinction, because the last section of this page is built on it.

The Message Is Nothing New

Here is what actually arrives at Vera's address. Read it and notice how little of it is unfamiliar.

POST /tandem-events HTTP/1.1
Host: reports.riverport.example
Content-Type: application/json
Tandem-Signature: t=1787853124,v1=9f2c4b...

{"event": "ride.completed",
 "delivery_id": "dlv_88f1",
 "occurred_at": "2026-08-27T17:52:03Z",
 "sent_at": "2026-08-27T17:52:04Z",
 "data": {"id": "rd_7c29", "bike_id": "bk_0412",
          "status": "completed", "end_station_id": "st_014"}}

A method, a path, a host, a couple of headers, and a JSON body. That is Chapter 2's anatomy of a request, unchanged, and Chapter 4's grammar, unchanged. The body says which event happened, gives the delivery its own identifier, stamps the time it was sent, and carries the ride object itself — the same rd_7c29, the same bike, now ending at Old Market.

Only one line is genuinely new, and it is the one named Tandem-Signature. It is how the office will know this message really came from Tandem, and it gets the whole of the next page. Everything else here you have been able to read since Chapter 4.

So what changed? Only the direction. For this one message Tandem is the client — it starts the exchange, it sends the request — and Vera's address is the server, sitting there waiting and answering. Chapter 1's rule that the client starts every exchange has not been broken; the two roles have simply swapped shoulders for one message. That is the entire trick, and it is why "webhook" needs no new protocol, no new tool, and no new grammar.

Receiving Without Programming

There is an honest catch, and it is the reason this page is about understanding rather than doing. To be sent a request, you must have something that can receive one: a program running somewhere, reachable from the public internet, awake at three in the morning when the ride ends. A laptop on office Wi-Fi is not that, and no setting makes it that.

Non-programmers cross this gap in two ordinary ways. The first is a webhook-capable tool — automation platforms and integration services sell exactly this as a product: they give you a URL, receive whatever is sent to it, and then do something visible with it, such as adding a row to a spreadsheet or sending a message. The second is the developer down the hall, who can stand up a receiver in an afternoon once someone tells them precisely what to expect.

Before either, there is a first experience Vera can have on her own today, and it is a genuinely complete one. Tandem's partner dashboard keeps a webhook log: every delivery it has attempted, with the exact body it sent and the answer it got back. Most providers have one. Registering a capture URL, triggering a test ride in the sandbox from Chapter 6, and then reading both sides in that log teaches nearly everything this page is about — without a line of code.

Push and Pull Compose

The last idea is the one that survives longest. Real systems do not choose between asking and being told. They use both, in a specific order that is worth naming.

The event arrives — the ride is over. The receiving side then makes an ordinary GET for the full, current detail: the ride's duration, the station's new count, whatever the report actually needs. The notification says that something happened; the request that follows finds out what is true now. Chapter 8's freshness logic decides the second step exactly as it always did.

Once you have seen event-then-fetch you will notice it constantly: the payment confirmed, then the order looked up; the file uploaded, then the file read. It is the shape modern products talk in, and it is built entirely out of things this book has already taught.