Webhook
Real-time HTTP callback notifying merchant system of payment events (approval, decline, chargeback). Critical for automated order fulfillment.
Overview
What is Webhook?
A webhook is an automated HTTP callback that notifies a merchant's system the instant a payment event happens — a successful charge, a decline, a chargeback, a refund, a subscription renewal, a fraud alert. Instead of a merchant's server repeatedly polling the gateway asking "did anything happen yet," the gateway pushes the event to the merchant the moment it occurs, which is what makes real-time automation — instant order fulfillment, inventory updates, customer notifications — possible in the first place.
Mechanically, a merchant registers a webhook URL in their gateway settings; when an event fires, the gateway sends an HTTP POST to that URL carrying the transaction ID, amount, status, and timestamp. The receiving server is expected to validate the request's signature against the gateway's secret key (to confirm it's genuinely from the gateway, not spoofed), process the event, and respond 200 OK — if no response comes back, the gateway retries automatically, typically 3-10 times over several hours, until delivery is confirmed.
At scale, webhooks stop being a convenience and become the only viable option: checking a dashboard manually works for ten orders a day and is impossible at five hundred. Instant, webhook-triggered fulfillment for digital goods alone typically cuts support tickets 40-60%, since customers get their product immediately instead of waiting and asking where it is. Webhooks also double as an early-warning system for chargebacks — a chargeback-filed webhook lands the moment it's opened, not days later when someone happens to check the dashboard, buying real time for representment preparation while evidence is still fresh.
The two failure modes that matter most are security and reliability: skipping signature validation lets anyone who discovers the webhook URL send fake "payment succeeded" events and trigger real fulfillment for nothing, while processing synchronously inside the webhook handler — rather than acknowledging in under a second and queuing the actual work — causes gateway timeouts, retries, and the duplicate order fulfillment that comes with them. Idempotency checks against the transaction ID close that second gap by recognizing and discarding the retries a slow handler otherwise triggers.
In depth
Everything you need to know.
You configure webhook URL in your payment gateway settings (e.g., https://yoursite.com/webhooks/payment). When events occur (payment succeeds, chargeback filed), gateway sends HTTP POST request to your URL containing event data (transaction ID, amount, status, customer info, timestamp). Your server receives request, validates authenticity (checking signature/token to prevent spoofing), processes event (fulfill order, update database, send email), and returns 200 OK response confirming receipt. If your server doesn't respond or errors, gateway typically retries (3-10 attempts over hours) to ensure delivery.
Webhooks enable real-time automation at scale. Without webhooks, staff must manually check gateway for successful payments, then fulfill orders - fine for 10 orders/day, impossible for 500+. Webhooks trigger automatic fulfillment within seconds of payment. For digital goods (courses, software, subscriptions), instant delivery improves customer satisfaction and reduces support tickets by 40-60%. Chargeback webhooks provide early warning. When chargebacks file, webhook notifies you immediately vs. discovering days later in dashboard. Early notification enables faster representment preparation, evidence gathering while transaction is fresh, and proactive customer contact to resolve disputes. Missing webhook notifications costs real money. If webhook fails and you don't fulfill orders, customers dispute charges as 'product not received,' creating chargebacks. Lost revenue plus chargeback fees.
Illustrative example — not a specific client engagement.
- Digital course platform used webhooks for instant access. Payment success webhook triggered automatic course enrollment and welcome email within 5 seconds. Without webhooks, manual fulfillment took 2-24 hours. Webhook automation reduced support tickets from frustrated customers by 70%.
- Supplement merchant didn't validate webhook signatures. Attacker discovered webhook URL, sent fake 'payment success' webhooks, triggering fulfillment of $8,500 in products before detection. After incident, implemented signature validation - all webhooks verified against gateway secret key.
- Gaming platform webhook handler processed synchronously, taking 15 seconds to fulfill orders. Gateway timeout was 10 seconds, causing retries. 40% of orders fulfilled 2-3 times (duplicate webhooks). Implemented async processing: acknowledge in 1 second, queue fulfillment. Eliminated duplicates, saved $12K monthly in duplicate shipments.
- Always validate webhook signatures using gateway-provided secret keys - prevents spoofed webhooks
- Respond 200 OK immediately, process asynchronously - acknowledge receipt in <1 second, queue actual fulfillment
- Implement idempotency using transaction IDs - track processed webhook events, ignore duplicates from retries
- Use try-catch error handling - one malformed webhook shouldn't crash entire system
- Log all webhook events to database - critical for debugging, reconciliation, and compliance
- Set up monitoring alerts for webhook failures - if no webhooks received in 1 hour during business hours, investigate
- Test webhook failure scenarios: simulate gateway downtime, network issues, malformed data - ensure graceful degradation
- Not validating webhook signatures - accepting any POST to webhook URL allows attackers to trigger fake order fulfillment
- Synchronous processing in webhook handler - performing 30-second fulfillment process before returning 200 OK causes gateway timeout and retries
- No idempotency checks - duplicate webhooks (from retries) fulfill same order twice, shipping duplicate products
- Not handling webhook failures gracefully - one broken webhook crashes entire order system
- Hard-coding assumptions about event data - gateway changes field names, breaks webhook processing
- No monitoring/alerting for webhook failures - miss hundreds of orders before noticing
Keep exploring
Related terms
Put this to work
for your business.
MIDs structures high-risk acquiring across 30+ banks — smart routing, fraud and chargeback control built in. Tell us your category and volume and we'll build the setup around it.