Webhook
What Is a Webhook in Payments? Definition and How It Works
Definition
A webhook in payments is an HTTP callback that a payment provider sends to a merchant's server to deliver real-time notifications when a transaction event occurs, such as an authorisation, capture, refund, or chargeback.
How it works
Webhooks are event-driven: instead of a merchant's system repeatedly polling the payment provider's API to check transaction status, the provider pushes a notification to a pre-configured endpoint on the merchant's server as soon as the relevant event occurs. The merchant's server receives the HTTP POST request, processes the payload, and returns a 200 response to acknowledge receipt.
Payment providers send webhooks for the key events in a transaction's lifecycle: authorised, captured, declined, voided, refunded, disputed, and chargeback received. Each event type carries a structured payload, typically JSON, containing the transaction ID, event type, status, timestamp, and relevant transaction details.
Webhook delivery is not guaranteed on the first attempt. Well-implemented webhook systems include retry logic: if the merchant's endpoint returns an error or times out, the provider retries delivery at increasing intervals. Merchants must design their webhook handlers to be idempotent, capable of receiving and processing the same event multiple times without duplicate side effects.
Webhook security requires verification. Because any server can send an HTTP POST to a public endpoint, merchants must verify that incoming webhooks genuinely originate from the payment provider. Standard approaches include HMAC signature verification (the provider signs the payload with a shared secret key) and IP allowlisting of the provider's outbound webhook IP ranges.
Why it matters
Webhook latency directly affects operational workflows: order fulfilment, fraud review queues, and customer notification systems that depend on payment status should be driven by webhooks rather than polling to ensure near-real-time responsiveness. Polling introduces unnecessary latency and API call overhead.
Missed webhooks cause operational failures: if a merchant's webhook endpoint is down during a chargeback notification, the dispute response window may lapse before the team is aware of it. Webhook monitoring and alerting should be treated as production-critical infrastructure.
Duplicate webhook handling must be built in: payment providers retry failed deliveries, which means merchants can receive the same event multiple times. Processing a capture webhook twice could result in duplicate fulfilment. Idempotency keys on transaction IDs prevent this.
Webhook payload versioning: payment providers update their webhook payload schemas over time. Merchants should subscribe to provider changelog notifications and test webhook handling against updated schemas before they go live.
With PXP
PXP sends webhooks for all transaction lifecycle events including authorisation, capture, refund, chargeback, and dispute updates. Webhook payloads are signed with HMAC-SHA256. PXP's dashboard provides a webhook event log with delivery status and manual retry capability for failed deliveries.
Frequently asked questions
What events should merchants configure webhooks for?
At minimum: authorisation result, capture confirmation, refund processed, chargeback received, and dispute status updates. Merchants with subscription billing should also subscribe to stored credential decline events. Each event type drives a different operational workflow: order management, fulfilment, finance reconciliation, and dispute response all depend on timely webhook delivery.
How should merchants handle webhook delivery failures?
Webhook endpoints should return a 200 status immediately on receipt, before any processing logic runs, to avoid timeouts that trigger unnecessary retries. Failed deliveries should be logged and alerted. Merchants should also implement a reconciliation check, a periodic API poll or batch file comparison, to catch any events that were never delivered despite retry attempts.
How do merchants verify webhook authenticity?
The standard approach is HMAC signature verification. The payment provider includes a signature in the webhook request header, computed by hashing the payload with a shared secret key. The merchant recomputes the hash on receipt and compares it to the header value. A mismatch means the request did not originate from the provider or was tampered with in transit.
What is idempotency and why does it matter for webhook processing?
Idempotency means that processing the same event multiple times produces the same outcome as processing it once. Because payment providers retry failed webhook deliveries, merchants may receive duplicate event notifications. Webhook handlers that are not idempotent, for example, triggering fulfilment on every capture notification, will produce duplicate actions. Using the transaction ID as an idempotency key prevents this.
Revolutionize your business with PXP
Take complete control of your commerce and payments with one platform.
Get Started