Webhook Testing

Why it matters

Webhooks run with nobody watching. A lost or doubly processed event usually shows no error on any screen: the paid order stays "pending", stock is reduced twice or the customer gets two receipts. The defect often surfaces days later, when it is hard to reproduce.

A webhook endpoint is also a public URL. Anyone who finds it can post a fake "payment succeeded" event, so signature verification is a security control, and an easy one to get wrong. Test it with forged and altered deliveries, only on systems you own or have written permission to test.

Callbacks, acknowledgements and retries

In the REST lessons the client asked and the server answered. A webhook reverses the roles: the provider's server is the client, and the consumer's endpoint receives the request. The consumer acknowledges a delivery by answering quickly with a 2xx status; any other status (3xx, 4xx, 5xx), a timeout or a refused connection is usually a failed delivery.

Many providers then retry, with growing gaps between attempts, for a limited period; some disable an endpoint that keeps failing, and some never retry and offer manual redelivery instead. Rules, timeout and schedule differ per provider, so its webhook documentation is your test basis.

Retries mean delivery is "at least once": if the consumer did the work but its response was lost or too slow, the same event arrives again. Each event usually carries an id that stays the same on every retry (some providers add a separate id per attempt), and that id is how a duplicate is recognised. Order is usually not guaranteed either: a retried payment.succeeded can arrive after the payment.refunded that followed it.

Idempotency: every event takes effect once

Processing is idempotent when handling an event twice has the same effect as handling it once, as with idempotent HTTP methods. The usual design stores the event id in a table with a unique constraint, a database rule that refuses a second row with the same value. If the id is already there, the consumer does nothing and still answers 2xx; an error status would only make the provider retry an event that was already handled. Ask what happens when the id is stored but the work then fails: the retry must not be skipped as a duplicate, or the event is lost.

Two copies can also arrive at once on two server instances. A "check, then insert" in code can let both through; the database's unique constraint stops the second. Against reordering, the consumer compares the event with the current state, so a refunded order never moves back to paid.

Signature verification

Many providers sign each delivery with an HMAC (RFC 2104): a hash computed with a secret key, so only a holder of the key can produce the right value, and changing one byte of the message changes the value completely. Usually it is HMAC-SHA256, with a secret only the provider and consumer know, over the exact raw body, often with a timestamp (Unix time: seconds since 1 January 1970 UTC) in front. The consumer recomputes the HMAC over the bytes it received and compares. A match shows that the sender knew the secret and the body was not changed; rejecting old timestamps limits the replay of a captured request. Providers usually sign each attempt afresh, so a retry hours later carries a new timestamp. Verify against the raw bytes: a handler that re-serialises the JSON first rejects valid deliveries with unusual spacing or key order. The scheme below is illustrative: each provider documents its own headers and format.

secret     shared value from the provider settings (test mode)
timestamp  1790000000, sent in the Pay-Timestamp header
input      "1790000000." + raw body bytes, exactly as received
signature  hex( HMAC-SHA256(secret, input) ), sent in Pay-Signature

consumer   recomputes over the raw bytes it received, compares with the
           header, and rejects a timestamp outside the tolerance window

Try it: Webhook Signature Analyzer Try it: HMAC Generator

Testing with a capture endpoint

A capture endpoint, often called a request bin, is a temporary public URL that records every request it receives. Register it as the webhook URL in the provider's test mode and trigger an event to see the real delivery: method, headers, raw body and timing. That tests the provider side before the consumer exists: compare the payload with the documentation and verify its signature with the test secret.

The capture then becomes test data for the consumer. Replay it, that is, send the same method, headers and raw body again, for example with cURL: unchanged and within the timestamp window to test duplicates, after the window to test that stale deliveries are rejected, and with one byte changed to test rejection. Inside the window only the thing you changed is wrong; outside it the old timestamp alone causes the rejection. Sign your own variants with an HMAC tool. To see retries, make delivery fail on purpose (stop the consumer, have it return 503, or point the provider at an endpoint that returns a 5xx status) and read the attempts in the provider's delivery log.

• A capture endpoint usually answers 200 to everything: it proves what the provider sent, not that your consumer works.
• Use test mode, test secrets and synthetic data only: captures are stored on a server for a while. Have any leaked secret rotated.

Try it: Webhook Tester Try it: Webhook Inspector Try it: Webhook Payload Formatter Try it: API Status Code Simulator

Worked example: tests for a payment webhook

Requirement: "On a valid payment.succeeded event, mark the order as paid and send one receipt. Deliveries are signed with HMAC-SHA256 over the timestamp and body; timestamps older than 300 seconds are rejected. The provider retries any non-2xx response and any response slower than 10 seconds." A captured delivery:

• W1: a valid new delivery → 2xx within 10 seconds, order 1042 PAID, one receipt.
• W2: the same delivery replayed, and W3: two copies at once → 2xx, one receipt, one stored event id.
• W4: amount changed to "1.00" without re-signing, a missing signature or another secret → 4xx, order unchanged, rejection logged.
• W5: valid signature, timestamp 300 and 301 seconds old → accepted, rejected (2-value boundary value analysis: "older than 300" leaves 300 in the accepted partition). The age grows in transit, so ask how it is measured and rounded.
• W6: payment.refunded handled before the retried payment.succeeded arrives → stays REFUNDED.
• W7: 503 to the first attempt → the provider retries, the retry succeeds, one receipt.

POST /webhooks/payments HTTP/1.1
Host: shop.example
Content-Type: application/json
Pay-Timestamp: 1790000000
Pay-Signature: sha256=<hex HMAC-SHA256 of "1790000000." + raw body>

{
  "id": "evt_7f3a91",
  "type": "payment.succeeded",
  "data": { "order_id": 1042, "amount": "190.00", "currency": "SAR" }
}

Frequently asked questions

References

• RFC 9110: HTTP SemanticsIETF · 2022The meaning of HTTP methods, header fields, status codes and content negotiation, independent of the wire version.
• RFC 2104: HMAC: Keyed-Hashing for Message AuthenticationIETF · 1997The HMAC construction: how a secret key and a hash function produce a message authentication code.
• ISTQB Certified Tester Foundation Level (CTFL) v4.0ISTQB · 2023The foundation syllabus of software testing: test levels and types, test design techniques, test management and tools.