Exercises¶
Hands-on tasks, roughly in order of difficulty. Each one maps to a real concept from these docs.
Browser learning path¶
Start the app with uv run uvicorn app.main:app --reload and open
http://localhost:8000. Predict the outcome before each action:
- Send a valid webhook: expect
200and a new received event. - Send a tampered webhook: expect
401and no new received event. Expand the experiment inspector: which exact bytes changed? - Replay a delivery: expect two
200s sharing one delivery ID, withduplicate: truein the second response. Why acknowledge a duplicate? - Add healthy, flaky, and dead subscribers; emit one event. Expect separate delivery IDs but the same event ID. With default settings, healthy takes one attempt, flaky takes three, dead exhausts four.
- Expand a delivery and inspect the raw body and signature header. Why would pretty-printing the JSON before verification be incorrect?
The lab calls the real receiver in-process; retries use actual HTTP callbacks. Only healthy/lab requests appear in Received events; flaky/dead simulate status codes only. State resets on server restart. See The dashboard for the UI/API mapping, then try the command-line and coding exercises below.
1. Forge and get rejected¶
Question: the receiver returns 401, not 400. Why is that the right
status code? What would 403 imply instead?
2. Watch retries happen¶
In the output, /webhooks/flaky shows [500, 500, 200] and /webhooks/dead
shows [500, 500, 500, 500]. Open GET /deliveries and check the attempts
array — the same X-Webhook-Delivery ID, rising X-Webhook-Attempt
numbers, growing gaps (0.5s → 1s → 2s).
Question: why does the retry of a delivery reuse the delivery ID, and what does the receiver do with that?
3. Inspect a delivery from the outside¶
Create a free URL at webhook.site, then:
curl -X POST localhost:8000/subscriptions \
-H 'Content-Type: application/json' \
-d '{"url": "https://webhook.site/<your-id>"}'
uv run python scripts/demo.py
Compare what webhook.site shows (headers, raw body) with what the local
receiver recorded in GET /events.
4. Add replay protection (Stripe-style)¶
Modify dispatcher.py to add an X-Webhook-Timestamp header and sign
timestamp.body instead of just body. Modify the receiver to reject
timestamps older than 5 minutes — before checking dedup.
Concepts: why does signing the timestamp prevent an attacker from stripping it? What breaks if subscriber and provider clocks drift?
5. Write a receiver in another language¶
The signature scheme is ~5 lines of stdlib HMAC anywhere — that's the point
of the standard. Write a receiver in Java (Spring Boot, Javalin, or the
JDK's built-in HttpServer), Node (express/crypto), or Go:
1. read raw body bytes
2. expected = "sha256=" + hex(HMAC_SHA256(secret, body))
3. constant-time compare with X-Hub-Signature-256
4. 200 on match, 401 otherwise
Then point send.py at it: uv run python scripts/send.py --url http://localhost:<port>/....
Bonus: run it on a second machine or VM and subscribe its LAN/public URL to the local provider — now the two sides really are separate servers.
6. Go live with GitHub¶
Follow Exposing your server to receive a genuine signed
push event. Then find GitHub's "Recent Deliveries" tab and compare its
view of the delivery with your /deliveries log — same concept, provider
and subscriber side.
7. Compare with the other transports¶
Run the sibling playgrounds — ../websockets-101 and ../grpc-101 — and
emit the same order.created event in each. Now kill each server
mid-delivery.
Question: which subscribers notice, and how? What machinery does each mechanism need to tolerate the other side being down?