Payment Webhooks: A Practical Guide for Merchants
By PayEurasia Team · 2 October 2026 · 6 min read
Last updated 2 October 2026
How payment webhooks work, signature verification, retries and duplicates, and the design of a consumer that never misses a payment update.
Webhooks are how a payment provider tells your system that something happened: a deposit succeeded, a payout failed, a refund completed. Getting them right is the difference between customers credited in seconds and a support queue full of "where is my money" tickets. This guide explains how webhooks work and how to build a consumer that is secure, idempotent and resilient.
What this guide covers
- Why webhooks instead of polling
- Verifying signatures
- Acknowledge fast, process later
- Handling duplicates and ordering
- Retries and failure recovery
- Testing and observability
Why webhooks instead of polling
Polling asks the provider repeatedly whether anything changed. It wastes requests, hits rate limits and still adds delay. Webhooks push events the moment they happen, which matters on instant rails like UPI and mobile wallets.
Polling still has a place as a safety net: a periodic sweep for transactions that should have received an event but did not.
Verifying signatures
Anyone can send an HTTP request to your endpoint, so every webhook must be verified. Providers sign the raw body with a shared secret using HMAC. Recompute the signature over the exact bytes received and compare in constant time before parsing anything.
Reject requests with stale timestamps to prevent replay, and rotate the signing secret periodically with an overlap window.
Acknowledge fast, process later
Return a 2xx response as soon as the event is verified and stored. Do heavy work — crediting balances, sending emails — asynchronously. Slow handlers cause timeouts, which cause retries, which cause duplicate processing.
A simple inbox table with the event ID, payload and processing status is enough for most merchants.
Handling duplicates and ordering
Providers deliver at least once, so duplicates are normal. Deduplicate on the event ID and make every state change idempotent, as described in idempotency in payment APIs.
Events can arrive out of order. Apply transitions only when they move a transaction forward in its lifecycle, and ignore stale ones.
Retries and failure recovery
When your endpoint fails, providers retry with backoff for a period. Monitor failed deliveries and alert on them. If your endpoint was down, replay missed events or query the API for the affected window.
Keep webhook endpoints separate from customer-facing traffic so a surge on one does not break the other.
Testing and observability
Use a sandbox to trigger every event type, including failures and refunds. Log every received event with its verification result and processing outcome, and build a small dashboard showing delivery latency and failure rate.
PayEurasia's API documentation describes event types, signatures and retry schedules in detail.
Frequently asked questions
What status code should my endpoint return?
A 2xx as soon as the event is verified and stored. Anything else triggers a retry.
How do I verify a webhook?
Recompute the HMAC signature over the raw body using your signing secret and compare it in constant time.
Can webhooks arrive twice?
Yes. Delivery is at least once, so deduplicate on the event ID.
What if my server was down?
The provider retries for a period; afterwards, replay events or query the API for the missed window.
Should I still poll?
Only as a periodic safety sweep, not as the primary update mechanism.
Where PayEurasia fits
PayEurasia runs local collections and payouts across Bangladesh, India, Pakistan and Nepal behind a single API, one reconciliation model and one settlement relationship. Provider redundancy sits behind that API, so an acquirer outage degrades approval rates instead of stopping money movement.
If you are scoping an integration, the API overview explains the object model and the API documentation covers authentication, webhooks and error handling. Merchant onboarding lists the documents needed before a live account is issued, and Compliance sets out the KYC and AML framework applied to every merchant.
Related guides
Talk to PayEurasia
Working in a high-risk vertical across South Asia? We can probably help.
Request integration →