Most payment bugs don't show up during checkout. They show up later — when the webhook fires, your server is too slow to respond, and the gateway marks the delivery as failed. By then the user is gone, the payment went through, and your order table still says "pending."
What actually happens after a payment completes
Once a transaction hits a terminal state — paid, failed, refunded — the gateway sends an HTTP POST request to a URL you registered in advance. That request carries a payload with the event type, transaction ID, status, and any relevant amounts. Your server reads it and decides what to do next: fulfil the order, trigger an email, update the record.
The gateway doesn't watch what happens after that. It checks one thing — did your server respond with a 2xx status code within the timeout window? Usually five to ten seconds. If not, it schedules a retry.
Why you can't skip signature verification
Every legitimate webhook includes a signature header. The gateway signs the raw request body using a shared secret — typically HMAC-SHA256 — and puts the result in a header like X-Signature. Your code recomputes that signature from the incoming body and compares. If they don't match, ignore the request.
Without this check, anyone who discovers your endpoint URL can send a fake payload claiming a payment was successful. The fix takes about ten lines of code. Skipping it is a real vulnerability, not a theoretical one.
The timeout window is smaller than it looks
Ten seconds sounds comfortable until your handler is querying the database, calling an email API, and writing a fulfilment record — all in sequence. Any one of those can run slow. If the total goes past the timeout, the gateway gets no response, marks the delivery as failed, and the retry clock starts.
The pattern that avoids this: accept the request, verify the signature, store the raw event, respond 200 immediately. Do the actual processing in a background job. Your processing time is now unbounded; the gateway gets its confirmation inside the window.
Testing this without a live account
Most provider sandboxes require you to expose a public URL, fire a test transaction, and wait for the event to arrive. Triggering specific scenarios — a signature mismatch, a delivery timeout, a retry sequence — is often not possible without workarounds that break between API versions.
MockGateway fires webhook events for every test transaction and lets you control delivery from the dashboard. Configure your endpoint URL, run a test payment, and watch the delivery log fill in — no account on any platform required. The playground is free to use from day one.
Tagged with
Found this helpful?
Share it with your network.
