Webhooks and events

At-least-once delivery

A courier who gets no signature comes back with the parcel the next day. Providers do the same. They retry when they don't get a 2xx: after a timeout, a 500, or a network error, often with backoff over hours or days. So delivery is at least once. The same event can arrive two or more times, for example when your 200 was lost on the way back. Events can also arrive out of order, like two letters crossing in the mail: payment.refunded before payment.succeeded.

The receiving rules follow from that:

• Verify first. No valid signature, no processing: answer 400 (or 401).
• Deduplicate by event id. Record each id you've handled. A repeat gets 200 without doing the work again. Answering 200 matters, because it tells the sender to stop retrying.
• Answer fast. Providers time out in seconds. Save the event and do the slow work (emails, model calls) in a background job, then reply.
• Don't trust order. Check the current state (for example, fetch the payment from the API) rather than assuming events arrive in sequence.

Combined, these make your handler idempotent: processing the same event twice has the same effect as once.

handled = set()
work = 0
for event_id in ["e1", "e1", "e2"]:
    if event_id in handled:
        continue
    handled.add(event_id)
    work += 1
print(work)

import hashlib, hmac

def sig(secret, t, body):
    return hmac.new(secret, f"{t}.".encode() + body, hashlib.sha256).hexdigest()

old, new = b"whsec_old", b"whsec_new"
body, t = b'{"id": "evt_1"}', 1793001234
header = f"t={t},v1={sig(old, t, body)},v1={sig(new, t, body)}"

parts = [p.split("=", 1) for p in header.split(",")]
candidates = [v for k, v in parts if k == "v1"]
for mine in (old, new, b"whsec_wrong"):
    ok = any(hmac.compare_digest(sig(mine, t, body), c) for c in candidates)
    print(mine.decode(), "->", "accepted" if ok else "rejected")

The sending side

If your product sends webhooks, you're the provider:

• Event objects have a stable shape: id, type (order.created), created, data. Document every type.
• Retry with backoff for a day or more, then mark the endpoint as failing and tell its owner.
• One secret per endpoint, shown once, with a way to rotate it.
• Guard against SSRF (server-side request forgery). Picture a stranger asking your assistant to fetch a parcel, and the address they give is your own locked office. Customers choose the URL, so someone will enter http://169.254.169.254/ or http://localhost:6379, hoping your server calls your own internal systems. Allow only public HTTPS addresses, and check which address the name points to before each delivery.
• Send a "thin" payload when data is sensitive: only the id and type, and let the receiver fetch details from your authenticated API.

A published standard, Standard Webhooks, uses webhook-id, webhook-timestamp and webhook-signature headers. Following it means receivers can use ready-made libraries.

Verify the bytes you received

The signature covers the exact bytes the provider sent, the way a seal covers a letter exactly as it was folded. If you parse the JSON and then re-serialize it to check the signature, the result will often differ, since spacing and key order can change. The check fails, or worse, you end up checking something else. Read the raw body first, verify that, and only then parse it.

import json

raw = b'{"id": "evt_1",  "amount": 500}'     # note the two spaces
print(raw == json.dumps(json.loads(raw)).encode())

Same data, different bytes. So the signature would no longer match.

Answer fast, work later

A receptionist signs for a parcel and opens it later. They don't keep the courier waiting while they unpack it. Providers wait only a few seconds for your reply. If you send an email, update three systems and then answer, you'll sometimes time out. The provider then thinks it failed and sends the event again, while your work is still going. So save the event, reply 200 straight away, and do the slow work in the background.

Don't punish duplicates

When you see an event id again, answer 200. A 4xx or 5xx tells the provider that delivery failed, so it keeps retrying for days, perhaps until it disables your endpoint.

And don't count on order. payment.refunded can arrive before payment.succeeded. Rather than assuming a sequence, treat each event as a hint to look at the current state: fetch the payment from the provider's API if you need to. That way, order stops mattering at all.

Test with replays

Save a few real events, signatures included, and replay them in your tests. You'll catch mistakes without waiting for the provider to send anything.