Verify webhook deliveries before acting

A webhook endpoint receives an ordinary HTTP request from the network. A field named event or paid is only a claim until the receiver authenticates the delivery according to its provider's protocol. In an HMAC scheme, the provider and receiver share a secret and compute a keyed digest over specified bytes. The receiver compares the supplied signature with its own computation using the protocol's constant-time comparison facility. TLS protects transport; it does not make every caller an authorized provider.

GitHub signs the raw request body with HMAC-SHA-256 in X-Hub-Signature-256. Stripe's signing scheme also binds a timestamp and its SDK enforces a timestamp tolerance. These are different protocols: do not invent a universal header parser or copy freshness behavior from one provider to another. JSON parsing and serialization can change whitespace, ordering or Unicode representation while preserving the same object. Verify the original bytes before body middleware transforms them; then parse and validate the authenticated content. Reject unsupported signature formats, missing secrets and malformed signatures before business work.

A valid signature establishes possession of the delivery secret for that message, not that the event is new, belongs to the intended account or is appropriate for the current order state. For this example, a signed paid event names order O17, provider account shop-red and amount 2500 USD cents. The receiver loads O17, requires account shop-red, currency USD, amount 2500 and an allowed unpaid-to-paid transition. Trusting the event's tenant field to choose an unrestricted database context would create a new authorization failure.

Durably record a verified event and enqueue its work before returning the provider's successful acknowledgement. Deduplicate with a unique key scoped to provider/account/event identity, and atomically couple that record to the local state change or durable work intent. Two concurrent deliveries must not both pass an in-memory seen check; this is the check-then-act race in /domains/appsec/business-logic/transaction-races/. For an external effect, use the recipient's idempotency mechanism and retain the operation identity across retries. Arrival order is not necessarily business order; fetch authoritative current provider state when ordering matters.

The program below implements the training protocol from the exercise with Python and SQLite. It verifies HMAC-SHA256(secret, "<timestamp>." + raw body) with hmac.compare_digest before parsing, rejects ages above 300 seconds, and then inserts the inbox row, marks the order paid and writes fulfill:O17 to the outbox in one transaction. A repeated event id hits the unique constraint and is acknowledged without a second effect; a new event id for an already paid order commits its inbox row but no outbox entry. Run python3 webhook_receiver.py; it prints PASS: 7 delivery cases, one fulfillment.

# Run: python3 webhook_receiver.py
import hashlib
import hmac
import json
import sqlite3

TOLERANCE = 300  # seconds, inclusive


class Rejected(Exception):
    pass


def sign(secret, timestamp, raw):
    """The training protocol: HMAC-SHA256 over b"<timestamp>." + raw body."""
    return hmac.new(secret, f"{timestamp}.".encode() + raw, hashlib.sha256).hexdigest()


def verify(secret, raw, timestamp, signature, now):
    if not timestamp.isdigit() or len(signature) != 64:
        return "malformed"
    if not hmac.compare_digest(sign(secret, timestamp, raw), signature):
        return "bad_signature"
    if abs(now - int(timestamp)) > TOLERANCE:
        return "stale"
    return "ok"


def handle(db, secret, raw, headers, now):
    result = verify(secret, raw, headers.get("t", ""), headers.get("sig", ""), now)
    if result != "ok":
        return 401, result  # nothing parsed, nothing stored
    event = json.loads(raw)  # parse only the authenticated bytes
    try:
        with db:  # inbox row, state change and outbox intent commit together
            db.execute("INSERT INTO inbox VALUES (?, ?, ?)",
                       ("training", event["account"], event["id"]))
            account, amount, currency, state = db.execute(
                "SELECT account, amount, currency, state FROM orders WHERE id = ?",
                (event["order"],)).fetchone()
            if (account, amount, currency) != (event["account"], event["amount"],
                                               event["currency"]):
                raise Rejected("context_mismatch")  # rolls back the inbox row
            if state == "paid":
                return 200, "already_paid"  # new event id, same effect: no outbox
            db.execute("UPDATE orders SET state = 'paid' WHERE id = ?", (event["order"],))
            db.execute("INSERT INTO outbox VALUES (?, ?)",
                       (f"fulfill:{event['order']}", event["order"]))
        return 200, "accepted"
    except sqlite3.IntegrityError:
        return 200, "duplicate"  # already committed: acknowledge, no new effect
    except Rejected as e:
        return 400, str(e)


def fresh_db():
    db = sqlite3.connect(":memory:")
    db.executescript("""
        CREATE TABLE inbox (provider TEXT, account TEXT, event_id TEXT,
                            UNIQUE (provider, account, event_id));
        CREATE TABLE orders (id TEXT PRIMARY KEY, account TEXT, amount INTEGER,
                             currency TEXT, state TEXT);
        CREATE TABLE outbox (operation TEXT UNIQUE, order_id TEXT);
        INSERT INTO orders VALUES ('O17', 'shop-red', 2500, 'USD', 'unpaid');
    """)
    return db


SECRET = b"training-endpoint-secret"


def delivery(t, event_id, account="shop-red", amount=2500, tamper=False):
    raw = json.dumps({"id": event_id, "account": account, "order": "O17",
                      "amount": amount, "currency": "USD"}).encode()
    sig = sign(SECRET, str(t), raw)
    if tamper:
        raw = raw.replace(b", ", b",")  # same JSON object, different bytes
    return raw, {"t": str(t), "sig": sig}


db = fresh_db()
assert handle(db, SECRET, *delivery(900, "e1"), now=1000) == (200, "accepted")
assert handle(db, SECRET, *delivery(900, "e1"), now=1000) == (200, "duplicate")
assert handle(db, SECRET, *delivery(950, "e5"), now=1000) == (200, "already_paid")
assert db.execute("SELECT COUNT(*) FROM outbox").fetchone() == (1,)
for case, expected in [
    (delivery(900, "e2", tamper=True), (401, "bad_signature")),
    (delivery(699, "e2"), (401, "stale")),  # age 301
    (delivery(700, "e3", account="shop-blue"), (400, "context_mismatch")),  # age 300
    (delivery(900, "e4", amount=25), (400, "context_mismatch")),
]:
    db = fresh_db()
    assert handle(db, SECRET, *case, now=1000) == expected, (case, expected)
    assert db.execute("SELECT COUNT(*) FROM inbox").fetchone() == (0,)
    assert db.execute("SELECT state FROM orders").fetchone() == ("unpaid",)
print("PASS: 7 delivery cases, one fulfillment")

Use the provider's library or its documented algorithm exactly; the schemes differ in the bytes they sign and in whether a timestamp is included. The function below verifies GitHub's header and is tested with the secret, payload and signature GitHub publishes for this purpose, so you can prove the function before wiring it to a route.

Compare with a constant-time function on equal-length values: hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js, which throws when the lengths differ, so check the length first, and MessageDigest.isEqual in Java. Stripe also publishes the addresses it sends from and recommends allowlisting them in addition to verifying signatures; an address allowlist alone does not authenticate a message.

# Run: python3 github_signature.py
import hashlib
import hmac


def verify_github(secret: str, raw_body: bytes, header: str | None) -> bool:
    """Checks X-Hub-Signature-256 against the raw request body."""
    if not header or not header.startswith("sha256="):
        return False
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)


# Test values published in GitHub's "Validating webhook deliveries" guide.
secret = "It's a Secret to Everybody"
header = "sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17"
assert verify_github(secret, b"Hello, World!", header)
assert not verify_github(secret, b"Hello, World! ", header)  # one extra byte
assert not verify_github("wrong secret", b"Hello, World!", header)
assert not verify_github(secret, b"Hello, World!", None)
print("PASS: GitHub test vector verified")

A legitimate signature failure is often a raw-body mismatch, wrong endpoint secret, header parsing problem or timestamp clock problem. Compare byte lengths and request identifiers, never print production signing secrets. Keep reverse proxies and frameworks from silently decoding or rewriting a signed body. Verify only with secrets configured for the receiving endpoint; a submitted key id or URL must not tell the server where to fetch an arbitrary secret.

During a planned rotation, an explicitly bounded overlap may allow old and new configured secrets if the provider supports that arrangement. Measure which secret version verified a delivery and retire the old one after the supported retry window. Keep freshness and deduplication separate: a timestamp can make a captured request too old, but multiple deliveries within the accepted interval can still duplicate work. Conversely, a provider retry may carry fresh signature material for the same event id. Verification tests should assert inbox rows, order state and outbox effects, not merely a 2xx response. The lab at /labs/webhooks/ asks you to fix a handler that pays twice, using these same checks.

CVE-2026-48747 was a signature-algorithm downgrade in Symfony's Mailomat webhook parser: it read the HMAC algorithm from the request's own signature header and passed it to hash_hmac(), so an attacker could pick a weak algorithm instead of the documented SHA-256. The missing control was pinning the algorithm server-side, as this guide does.

Imagine an invoice is paid and then refunded, but the refund delivery arrives before an earlier paid delivery. A receiver that blindly applies each event as a new status can finish with paid, contradicting the provider's current state. Deduplicating event ids does not solve this because the two events are distinct. Choose a state-transition policy that tolerates ordering, or retrieve the provider's authoritative current object when the event is a notification of change. Do not sort by an arbitrary delivery timestamp unless the provider explicitly gives that field the ordering semantics you need.

Different event ids may also describe the same business effect. A unique inbox event key prevents processing the identical event twice, while a unique fulfillment operation for O17 prevents two different accepted notifications from shipping the same order twice. Those constraints belong at different semantic levels. In the pseudocode, record the paid transition and fulfillment intent transactionally. If a duplicate business event arrives after payment, recognize the already-completed transition and avoid another outbox effect according to the operation contract.

Verification should include a response lost after durable commit, a worker crash after external acceptance, two simultaneous copies of one event and two different event ids about the same order. Count both inbox receipts and business effects. Two verified inbox rows can be legitimate, while two shipments for one paid order are not. This distinction makes operational dashboards useful during provider retries rather than treating every duplicate as an attack.

Repair the code

Webhook signature and replay lab: Repair a webhook handler that pays twice

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. GitHub: validating webhook deliveries
2. GitHub: webhook best practices
3. Stripe: receive Stripe events in your webhook endpoint (signatures, replay tolerance, retries, duplicates)
4. Standard Webhooks specification
5. Python hmac.compare_digest. Python 3.15.
6. MITRE CWE-347: improper verification of cryptographic signature. CWE 4.20.
7. NVD: CVE-2026-48747, webhook signature algorithm downgrade in Symfony

Reference information

Tags

API security

SDLC phase

DesignDevelopment

Role

DevelopersAppSec engineers

Download this guide as Markdown

Continue exploring