The dashboard¶
Open http://localhost:8000 while the server is running. The dashboard is a
live view of the entire webhook lifecycle — one app playing both roles,
so you can watch a delivery travel from "something happened" to "event
received" in real time. It polls GET /state every 1.5 seconds; everything
it does can also be done by hand through the API (/docs).
Provider (this app) ──signed HTTP POST──► Subscriber (this app)
/emit, dispatcher.py X-Hub-Signature-256 /webhooks/receive
Start here: predict, run, inspect¶
Start with the three experiment cards. No subscriptions or terminal commands are needed after starting the server.
| Experiment | Predict | Observe | Learn |
|---|---|---|---|
| Send a valid webhook | Will a matching signature pass? | 200, one new received event |
HMAC authenticates the exact body bytes |
| Send a tampered webhook | Can a changed amount pass? | 401, no received event |
Changing 10 to 99 after signing invalidates the signature |
| Replay a delivery | Will the second request be rejected? | Two 200s, then duplicate: true |
Acknowledge retries while preventing repeated business work |
Open Inspect experiment bodies and responses to compare signed_body,
sent_body, the delivery ID, and HTTP responses. These buttons call
POST /lab/valid, /lab/tampered, and /lab/duplicate. The lab invokes the
real /webhooks/receive handler in-process, never an arbitrary target, and
never returns the configured signing secret. It does not create provider
/deliveries entries; inspect Received events instead.
The app logs both duplicate receipts and flags the second. It does not implement a database-backed business-processing queue. Deduplication is in memory and resets on restart; real systems need persistent idempotency records. The UI shows connection errors and reports invalid event JSON without sending it.
① Subscribers — who's listening¶
This is the subscription step: the moment you paste a URL into GitHub's Settings → Webhooks. A subscriber is just a URL the provider will POST to.
- + healthy receiver — subscribes
/webhooks/receive. Verifies the signature, dedupes, records the event. - + flaky receiver — subscribes
/webhooks/flaky. Returns500for the first two attempts of every delivery, then succeeds — this is how you see retries happen. - + dead receiver — subscribes
/webhooks/dead. Always fails, so you can watch a delivery exhaust its retries and die. - Paste any public URL (e.g. a
webhook.siteURL) to see what a delivery looks like from the outside.
See The players for why the URL owner is the subscriber, and Exposing your server to give localhost a public URL.
② Emit — "something happened"¶
POST /emit plays the role of the event itself — a push on GitHub, an
invoice.paid on Stripe. The provider serializes the event, signs it, and
fans out to every subscriber in parallel. The packet animation on the wire
marks this moment.
③ Deliveries — provider side¶
One card per delivery: event type, target URL, final status, and an
attempt timeline — each attempt's HTTP status with the backoff delay
between them (0.5s → 1s → 2s, configurable via RETRY_DELAY_SECONDS and
MAX_ATTEMPTS).
Click a card to inspect the exact request that was sent:
- the headers —
X-Webhook-Event,X-Webhook-ID,X-Webhook-Delivery,X-Webhook-Attempt, andX-Hub-Signature-256(highlighted). These mirror GitHub'sX-GitHub-*headers — see Anatomy of a delivery. - the raw body — the signature covers these bytes, which is why receivers must verify the raw body, not re-serialized JSON (Security).
- the delivery ID — the idempotency key a receiver dedupes on (Receiving).
④ Received events — subscriber side¶
What /webhooks/receive accepted. Each row shows the three things a correct
receiver does:
- ✓ signature verified — anything failing this got a
401and never appears here. (Forge one withscripts/send.py --bad-secret.) - ✓ new delivery id / ⚠ duplicate — retries mean the same delivery can arrive twice; receivers dedupe on the delivery ID.
- ✓ 200 OK returned — respond fast; a slow receiver just triggers retries. Click a row to see the payload it recorded.
Try this sequence¶
- Subscribe the healthy receiver → emit → one attempt,
200. - Subscribe flaky → emit → attempts
500, 500, 200with waits between. - Subscribe dead → emit →
MAX_ATTEMPTSfailures (four by default), statusfailed. Flaky/dead are status simulators: neither verifies signatures nor adds to Received events. Flaky succeeds on attempt three only whenMAX_ATTEMPTSis at least three. - Subscribe a
webhook.siteURL → emit → compare what it saw with ④. uv run python scripts/send.py --bad-secret→ the event never reaches ④.
Then work through the exercises.