I polled an endpoint hoping to catch a change. A webhook inverts that: the server calls you when it happens. But the call can be forged, so you verify the signature first.
About 2 min of reading
Receive a webhook and reject a forged one before acting.
A genuine event arrives with a valid signature. You act and answer 200.
Before you run it, say out loud what it will print. Then open the answer.
A forged POST to the same URL has no valid signature. Reject it before acting.
Before you run it, say out loud what it will print. Then open the answer.
A webhook URL is public and forgeable. Never trust the body alone. Verify the signature over the raw bytes (the exact bytes received, not a re-serialised copy) before doing anything, and return a non-200 so the service knows to retry.
Handlers run on a hot path. Do the work fast or hand it to a queue, and make it idempotent using the event id, because services resend events. A handler that double-counts on a resend is the classic webhook bug.
poll every 5s -> spam, late, wasteful
webhook -> one POST when it happensPolling asks and waits. A webhook is the answer arriving when the event fires. One request, no loop, no delay.
{"event": "charge.succeeded", "id": 42}The server POSTs you a body when the event happens. Your job is to read it and act, quickly and without blocking.
expected = hmac(secret, raw_body)
if not hmac.compare_digest(sig, expected): return 402Anyone can POST your URL. Recompute the signature over the exact bytes and reject a mismatch before you act.
Each one is defined here on this site. Open the entry for the full definition and the other words it points at.