7. Chapter review

Polling wins when the job is short (seconds), the system is internal, and adding a webhook endpoint creates more operational surface than it saves. Webhooks win when jobs are long (minutes-to-hours), when polling burns through rate limits or per-execution billing, when latency-to-notification is user-facing, or when you would otherwise need many concurrent connections holding open. The Receipt Scanner in Chapter 21 ran synchronously -- requests.post() blocked until OCR.space returned -- because the jobs are short. Polling and webhooks are both ways to handle the long-running variant; Chapter 21 sketched polling at the end of receipt-scanner.njk, and this chapter builds the webhooks variant.

The provider waits while your handler waits on Slack. If Slack is slow or down, your handler exceeds the provider's timeout (typically ~10 seconds for GitHub), the provider retries -- which means you Slack-post a second time when Slack eventually answers -- and after enough retries the provider may disable the webhook entirely. The two fixes are persist + acknowledge fast (store the event in SQLite, return 200 in milliseconds, never call Slack from the handler) and process in a background worker (a separate process drains the queue, retries on its own schedule, and is allowed to be slow).

The handler tries to insert the event, hits the UNIQUE constraint on delivery_id, catches the integrity error, and returns 200 immediately without doing any downstream work. delivery_id is the right key because the provider guarantees uniqueness per delivery -- two webhooks with the same body but different deliveries (legitimate duplicate events) will get different IDs and be processed normally, while two retries of the same delivery (the case dedup is for) share the ID. Hashing the body would conflate those two cases.

HMAC verifies sender authenticity: the request came from someone holding the shared secret, and the body has not been altered between signing and your verification. It does not verify body confidentiality -- the payload is plaintext over HTTPS, and any TLS-terminating intermediary (Cloudflare, your load balancer, a logging proxy) sees it in the clear. It also does not provide non-repudiation in the cryptographic sense, because both sides hold the secret. The right mental model is "this request came from someone who knew the secret" plus "the body matches what they signed," nothing more.

Treat the secret as compromised: rotate it immediately. In GitHub repository settings, generate a new secret, update GITHUB_WEBHOOK_SECRET in your environment (Railway Variables tab, local .env, or wherever you store it), and redeploy. The attacker can forge requests that pass HMAC verification, so they can trigger your worker as if the events were real -- which means they can fan out Slack notifications, write rows into your database, or trigger any downstream side effect your worker performs. They cannot retrieve past payloads or impersonate GitHub on the wire (TLS protects the transport); the damage is bounded to "things your handler does on receipt."

Two reasons. (1) Provider isolation. If GitHub changes its payload shape -- not impossible across major API versions -- only the normaliser changes; everything downstream (Slack formatting, status updates, database writes) sees the same internal shape. (2) Multi-provider readiness. Adding a Stripe or GitLab feed later means writing a new normaliser that produces the same internal shape; the Slack code does not change. The cost is one small dictionary; the payoff is that the rest of your code stops caring about which provider an event came from.

Production uses a stable URL. When you deploy the receiver to Railway (per the deployment paragraph at the end of Section 6), Railway gives you a permanent your-app.up.railway.app domain. You register that URL in GitHub once and it stays valid as long as the service runs. ngrok is a development convenience -- public tunnel to your laptop -- not a production hosting strategy. The free-tier URL churn is fine because dev sessions are short; in production the receiver is a long-lived service with a fixed address, exactly the same shape as the Music Time Machine deployment in Chapter 20.