Webhooks push events instead of polling

Thu, 18 Nov 2027 00:00:00 +0000

Because the call comes from outside, delivery becomes at-least-once, so a receiver must tolerate retries and prove the origin rather than assume it is safe.

One event, one callback

A webhook turns the usual direction of an API call around: instead of a client polling for fresh data, the provider sends an HTTP request to a URL you registered whenever an event happens. The payload is a small, self-contained description of what changed, delivered straight to an endpoint that is often on an entirely different server. Because the publisher initiates the call, the subscriber stops reopening connections and simply waits for something to arrive, which is how delivery can feel nearly instant without continuous polling.

Retries and dedup belong to the receiver

Retries and deduplication are the receiver’s job. The publisher re-sends a webhook if it cannot reach you or if you do not acknowledge in time, and once it does, the same event can arrive more than once, so the endpoint must be idempotent. The receiver should remember the event ids it has already handled, treat a duplicate as a no-op, and do heavy work in a queue or out-of-band instead of waiting synchronously inside the request. Speed up acknowledgment, make garbage collection explicit, and the noisy network becomes harmless where it used to be a failure.

Verify the caller, not just the TLS

Verifying the caller goes beyond checking the TLS layer. Because the request arrives over public HTTP, you must fetch the signature and recompute it with the shared secret to confirm the payload is authentic, and bind acceptance to a per-event timestamp so old requests are refused. Tie the callback to a fixed, known URL and rotate the secret on a schedule, because a forged webhook can act exactly like a real one. The minimal honest shape is acknowledge quickly, process idempotently, and verify the signature on every delivery; nothing is trusted by default.

When it breaks

Delivery fails quietly when the sender gives up too early. If the publisher retries only twice with no backoff, a short deploy or a cold start can lose an order-paid notification forever, and the receiver never knows it missed anything. A slow endpoint turns that gap into a backlog: when signature checks and database writes all run inside the request handler, timeouts pile up, the sender marks each attempt as failed, and the retry storm replays the same queue again. Acknowledge first, enqueue the payload, and let a worker do the heavy work, so a spike becomes visible queue depth instead of silent loss.

Trust breaks in quieter ways. A secret rotation that updates the sender but not every verifier rejects all genuine deliveries until both sides agree again, which looks like a forgery flood on a dashboard. Without a timestamp window and a record of handled event ids, an attacker can replay a captured payment webhook days later and trigger fulfillment twice. A debug route that logs full bodies can leak personal data, while a handler that returns success before validating lets poisoned events look healthy.

Check it quickly

Save the following as webhook_verify_demo.py in a scratch directory and run python3 webhook_verify_demo.py. It uses only the Python standard library, signs a fake payment event with HMAC-SHA256 over a timestamped message, and asserts five behaviors. No network access or third-party package is needed.

import hashlib
import hmac
import time

SECRET = b"whsec_test_secret_1"
OLD_SECRET = b"whsec_old_secret_0"
TOLERANCE_SECONDS = 300
seen_ids: set[str] = set()


def sign(event_id: str, timestamp: int, payload: bytes, key: bytes = SECRET) -> str:
 msg = f"{event_id}.{timestamp}.".encode() + payload
 return hmac.new(key, msg, hashlib.sha256).hexdigest()


def verify(event_id: str, timestamp: int, payload: bytes, signature: str, now: int | None = None) -> bool:
 if now is None:
 now = int(time.time())
 if abs(now - timestamp) > TOLERANCE_SECONDS:
 return False
 if event_id in seen_ids:
 return False
 expected = sign(event_id, timestamp, payload)
 if not hmac.compare_digest(expected, signature):
 return False
 seen_ids.add(event_id)
 return True


def main() -> None:
 now = int(time.time())
 payload = b'{"type":"order.paid","order":"42"}'

 fresh = sign("evt_1", now, payload)
 assert verify("evt_1", now, payload, fresh, now) is True

 tampered = b'{"type":"order.paid","order":"43"}'
 assert verify("evt_2", now, tampered, fresh, now) is False

 stale_sig = sign("evt_3", now - 3600, payload)
 assert verify("evt_3", now - 3600, payload, stale_sig, now) is False

 assert verify("evt_1", now, payload, fresh, now) is False

 rotated_sig = sign("evt_5", now, payload, key=OLD_SECRET)
 assert verify("evt_5", now, payload, rotated_sig, now) is False

 print("PASS: fresh accepted; tampered, stale, replay, rotated key rejected")


if __name__ == "__main__":
 main()

The demo accepts one fresh delivery, then rejects four bad ones: a tampered body with a mismatched signature, a timestamp one hour old outside the five-minute tolerance, a replayed event id that reuses an accepted signature, and a signature made with the rotated-out key. Each rejection returns false without recording the event, so only the first delivery enters the seen set. Future timestamps beyond the same tolerance are rejected for the same reason.

The assertions passed with Python 3.11 on macOS. The fixture models verification logic only, not HTTP routing, persistent storage, or provider-specific header names. Before deployment, repeat the checks against your real endpoint with two secrets during rotation and a persistent record of handled event ids.

Sources

GitHub webhook documentation, covers retries and verification, checked 2026-06-12.
Stripe webhooks documentation, covers signatures, retries, and idempotent handling, checked 2026-06-12.

Events · XB Field Notes