Webhooks push an event to your server the moment something happens, such as a code arriving for an order. They remove the need to poll and cut latency. They also introduce a new failure mode: your endpoint must be up, fast and safe to call.
Acknowledge fast, process later
The sender expects a quick 2xx response. If your handler does heavy work inline, you risk timeouts, and the sender will retry, creating duplicates. The reliable pattern is to validate the request, write the raw event to a queue or table, return 200, and process asynchronously.
Verify the signature
Anyone who knows your URL can post to it. Require a signature header computed from the raw request body and a shared secret, and compare it in constant time. Verify against the raw bytes, not a re-serialised JSON object, because whitespace and key order change the digest.
expected = hmac.new(secret, raw_body, 'sha256').hexdigest()
ok = hmac.compare_digest(expected, header_signature)Also check a timestamp in the payload and reject events older than a few minutes. That blocks simple replay of captured requests.
Assume duplicates and out of order delivery
At-least-once delivery means you will sometimes see the same event twice. Store an event identifier and skip anything already processed. Out-of-order arrival is also possible, so make state transitions monotonic: an order that is already marked received should never move back to waiting because a late event showed up.
Retry and dead letter handling
Expect the sender to retry on non-2xx responses with growing delays. On your side, return 5xx only for genuine temporary problems. Return 4xx for payloads you will never accept, otherwise you create an endless retry loop. Keep a dead letter table for events that fail processing so an engineer can inspect and replay them.
Provide a safety net
Even a perfect endpoint can miss events during a deploy or an outage. Run a lightweight reconciliation job that lists recent orders still marked waiting and fetches their status directly. This hybrid keeps webhook speed while guaranteeing eventual correctness.
Operational checklist
- Serve the endpoint over HTTPS with a valid certificate.
- Log event id, order id, signature result and processing time.
- Alert when the delivery failure rate or queue age rises.
- Rotate the signing secret on a schedule and support two active secrets during rotation.
- Document the payload schema and version it.
A webhook endpoint is a public door into your system. Treat it with the same care as a login form and it will deliver codes quickly and quietly for years.
Frequently asked questions
How fast must my endpoint respond?
Aim for well under a second, and treat five seconds as a hard ceiling. Many senders time out earlier than you expect. Store the event, return success and do the real work in a background job so slow dependencies never cause redelivery.
What if my server was down for an hour?
The sender will retry for a while, but not forever. After an outage, run your reconciliation job to list orders still waiting and fetch their status directly. That closes any gaps left by events you never received.
Can I test webhooks locally?
Yes. Use a tunnelling tool to expose a local port over HTTPS, and keep a library of saved sample payloads. Replay them against your handler, including duplicates and out of order sequences, so you see real behaviour before going live.
What should I do about webhook secrets in multiple environments?
Use a different signing secret for every environment and every endpoint. If a staging secret leaks, production stays safe. Store secrets in your secret manager, rotate them on a schedule, and support a short overlap period where both the old and the new secret are accepted, so a rotation never drops events.
Next steps
Explore the supported services to see what is available today, and read the API documentation if you plan to automate. The about page explains how the platform works, the help center answers common questions, and you can contact the team about anything specific. For more guides, browse the blog. When you are ready, sign in to start a verification.
Related reading: Polling vs Webhooks for Receiving OTP Codes and API Authentication: Keys vs Tokens for Verification Services.
