webhooks-101¶
A hands-on guide to webhooks, built around a working playground you can run locally: a tiny FastAPI app that is both a webhook provider and a webhook receiver, so you can watch the entire lifecycle in one process.
What is a webhook?¶
A webhook is a reversed API call. With a normal API, you call the service to ask "did anything happen?". With a webhook, you give the service a URL once, and it calls you the moment something happens:
sequenceDiagram
participant App as Your app (subscriber)
participant GH as Provider (e.g. GitHub)
App->>GH: 1. "POST events to https://me.example/webhooks/receive"
Note right of GH: ... time passes ...
GH->>App: 2. POST /webhooks/receive (signed JSON)
App->>GH: 3. 200 OK
No polling, no waiting — the provider pushes the event to you.
The two roles¶
| Role | Also called | What it does | In this repo |
|---|---|---|---|
| Provider | publisher, sender, notification server | Owns the events. Lets others subscribe, then POSTs signed events to them | POST /emit, app/dispatcher.py |
| Subscriber | consumer, receiver, listener | Owns the callback URL. Registers it with the provider, receives and processes events | POST /webhooks/receive |
Who acts as the subscriber?
You do — whoever wants to be notified. When you paste a URL into GitHub's Settings → Webhooks page, your application is the subscriber and GitHub is the provider. Confusingly, some docs call the provider the "webhook" itself — read The players for the full vocabulary.
Run it¶
uv sync
cp .env.example .env
# terminal 1 — the server (provider AND receiver in one)
uv run uvicorn app.main:app --reload
# terminal 2 — the whole lifecycle in one command
uv run python scripts/demo.py
Open http://localhost:8000 for the live dashboard — an interactive
view of the whole lifecycle: subscribe URLs, emit events, and watch signed
deliveries retry and land. See The dashboard for a tour of
each panel. Start with the valid, tampered, and replay experiments:
predict the status, run the request, then inspect the response and raw bodies.
Next add healthy/flaky/dead subscribers and compare their retry timelines.
The browser learning path follows this exact
sequence. Tests: uv run pytest.
This is an unauthenticated local learning tool. Use synthetic data; do not deploy it as a public webhook service. All state resets when the process restarts.
Serve this documentation locally:
Where to go next¶
- The dashboard — the fastest way to see it: panels for subscriptions, emitting, deliveries/retries, and received events.
- The players — who is the subscriber, who is the notification server, and what each owes the other.
- Anatomy of a delivery — the exact headers and body every webhook carries (the same ones the dashboard shows per delivery).
- Receiving / Sending — the two halves of the implementation.
- Security — how signatures prove a request is genuine.
- Exposing your server — tunnels, and how to receive real GitHub webhooks on your laptop.
- Alternatives to webhooks — when websockets or gRPC streams are the better tool.
- Exercises — hands-on tasks that cement it all.
The sibling playgrounds¶
This repo is one of three — the same toy flow over different transports:
../websockets-101— events pushed down open sockets: no public URL, no signatures, no retries.../grpc-101— events over a server-streaming RPC: the open call is the subscription.