How Webhooks Work
Webhooks follow a straightforward event-driven pattern: your system registers a URL, an event occurs on the provider's side, and the provider delivers a JSON payload to that URL via HTTP POST. Understanding each step helps you build integrations that are both reliable and secure.
Register your endpoint
Log into your payment provider's dashboard (or call its API) and provide the HTTPS URL where you want to receive events. Select which event types — such as payment.captured or dispute.opened — you want to subscribe to. The provider stores your endpoint and begins routing matching events to it.
Event fires on the provider side
When a customer completes a payment, the payment gateway records the outcome and emits a structured event. This event contains a unique ID, a timestamp, the event type, and a full data object describing the transaction — amounts, currency, card metadata, and status codes.
Provider sends the HTTP POST
The provider signs the payload using HMAC-SHA256 with a shared secret and sends it as an HTTP POST to your registered URL. The signature is included in a request header (e.g., Stripe-Signature or X-Adyen-HMAC-SHA256) so you can verify authenticity before processing.
Your server verifies and acknowledges
Your handler recomputes the HMAC signature and compares it to the header value. If valid, it immediately returns HTTP 200 to acknowledge receipt. Returning anything other than a 2xx status code signals failure and triggers the provider's retry mechanism.
Payload is processed asynchronously
After acknowledging, your server enqueues the payload for background processing — updating order status, triggering fulfilment, sending confirmation emails, or writing to your analytics pipeline. Keeping processing out of the synchronous response window prevents timeouts on large batches.
Why Webhooks Matter
Webhooks are not a convenience feature — they are the operational core of any real-time payment stack. Without them, merchants resort to polling, which is slow, wasteful, and unreliable at scale.
According to Stripe's developer survey, teams using event-driven webhook architectures reduced payment reconciliation time by an average of 70% compared to polling-based approaches. Separately, research from Adyen's 2023 developer report found that webhook-driven order management decreased false payment failures (cases where an order was not fulfilled despite a successful charge) by up to 40% for high-volume merchants. A further industry benchmark from MRC (Merchant Risk Council) noted that real-time dispute notification via webhooks cuts chargeback response times from days to under four hours — a critical window given most schemes allow only 7–20 days to respond.
Why speed matters
Card networks typically give merchants 7–20 calendar days to respond to a chargeback. Webhook-driven dispute alerts fired within seconds of a dispute.opened event give ops teams the maximum possible response window.
Webhooks vs. Polling
Both webhooks and polling retrieve data from an external system, but they differ fundamentally in who initiates the data transfer, how quickly updates arrive, and what they cost at scale.
| Dimension | Webhooks | Polling |
|---|---|---|
| Initiation | Provider pushes to you | You pull from provider |
| Latency | Milliseconds (real-time) | Seconds to minutes |
| Infrastructure cost | Low — only triggered by events | High — constant requests |
| Reliability | Retry logic built in | Missed intervals = missed events |
| Implementation effort | Endpoint + signature verification | Scheduled job + diffing logic |
| Rate limit risk | Minimal | High on frequent intervals |
| Scalability | Scales with event volume | Degrades under high-frequency polling |
| Duplicate handling | Required (retries are expected) | Less common |
For payment operations, webhooks are almost always the right choice for event-driven flows. Polling remains useful for scheduled reconciliation jobs or querying historical transaction data via a sandbox environment during testing.
Types of Webhooks
Payment providers expose several categories of webhook events. Understanding the taxonomy helps you subscribe only to what you need and design appropriate handlers for each class.
Transaction lifecycle events cover the journey of a single payment: authorization, capture, partial capture, decline, void, and refund. These are the most common and typically the first a merchant integrates.
Dispute and chargeback events notify you the moment a cardholder raises a dispute or a chargeback is filed. Providers like Adyen and Braintree include the reason code, scheme deadline, and supporting evidence requirements directly in the payload.
Subscription and recurring billing events fire on renewal attempts, failed recurring charges, trial expirations, and plan changes. These are critical for SaaS and subscription commerce operators who need to manage dunning workflows automatically.
Payout events notify you when funds settle into your bank account, flagging the settlement amount, currency, and any associated fees. Useful for automated accounting reconciliation.
Fraud and risk events are emitted when a transaction is flagged, placed in review, or rejected by the provider's fraud engine. Integrating these allows real-time hold logic in your order management system.
Account and configuration events cover changes to your merchant account — API key rotation, user permission changes, or compliance status updates. Less frequent but important for platform operators managing sub-merchants.
Best Practices
Good webhook hygiene separates integrations that degrade silently from those that recover gracefully under load, downtime, and adversarial conditions.
For Merchants
Always enable webhook notifications for at minimum four event types: payment captured, payment failed, dispute opened, and refund settled. These four cover the scenarios most likely to break your order management workflow if missed. Keep your registered endpoint URL on a dedicated subdomain (e.g., hooks.yourdomain.com) with its own rate limits and monitoring, isolated from your customer-facing application. Subscribe to your provider's status page so planned maintenance windows can be cross-referenced against webhook delivery gaps.
Store each raw payload verbatim before any transformation. This creates an audit trail for disputed transactions and simplifies debugging when your processing logic changes.
For Developers
Respond with HTTP 200 within 5 seconds — most providers timeout and retry if no response arrives within that window. Offload all business logic to an async queue (Redis, SQS, RabbitMQ) and return immediately. Implement idempotency by indexing on the event's unique ID field before writing state changes; reject duplicates silently with a 200 rather than a 4xx to avoid unnecessary retries.
When using an SDK, use the built-in webhook verification helpers rather than rolling your own HMAC code. Stripe, Adyen, and PayPal SDKs all include verified helper methods that handle timestamp tolerance and encoding edge cases automatically. Version your handlers — when a provider updates its event schema, a versioned handler lets you migrate incrementally without breaking live traffic.
Common Mistakes
Skipping signature verification. Treating any POST to your webhook URL as legitimate opens you to spoofed events that could trigger fraudulent fulfilment or false refunds. Always verify HMAC signatures on every request, even in staging.
Processing synchronously in the request handler. Performing database writes, sending emails, or calling downstream APIs inside the HTTP response cycle causes timeouts on anything over 2–3 seconds. The provider interprets the timeout as failure and retries — creating duplicates.
Assuming exactly-once delivery. Providers guarantee at-least-once delivery, not exactly-once. Any integration that does not implement idempotency will create duplicate records, double-charge customers, or fulfil orders twice when retries arrive during an outage recovery window.
Using HTTP instead of HTTPS. Sending payload data — which often includes partial card numbers, amounts, and customer identifiers — over unencrypted HTTP violates PCI DSS requirements and most provider terms of service. Every webhook endpoint must use TLS 1.2 or higher.
Not logging failed deliveries. Providers expose a webhook event log in their dashboards, but your own application should also record delivery failures and processing errors. Without local logs, debugging a missed fulfilment event days later becomes near-impossible.
Webhooks and Tagada
Tagada's payment orchestration layer is built around a unified webhook model. Rather than managing separate webhook subscriptions across each processor in your stack, Tagada normalises events from all connected payment gateways into a single, consistent event schema and delivers them to a single endpoint on your server.
Unified event stream
When you route payments across multiple processors through Tagada, you receive one normalised payment.captured event regardless of whether the underlying transaction settled via Stripe, Adyen, or Worldpay. Your handler code stays the same no matter how your routing rules change.
This matters operationally: when you add a new processor to your routing rules or run A/B tests across acquirers, your webhook handler requires zero changes. Tagada also exposes a webhook replay tool in the dashboard, letting you resend any event from the last 30 days — useful for recovering from endpoint downtime or debugging new handler logic against real production payloads.