The Webhook Delivery Mechanism
A webhook is an HTTP POST request that a payment gateway sends to a merchant-configured URL when a payment event occurs. Unlike a REST API call (which the merchant initiates), a webhook is initiated by the gateway and received by the merchant's server. The gateway POSTs a JSON payload containing the event type, the relevant invoice or transaction details, and a cryptographic signature that the merchant uses to verify authenticity.
The delivery model is fire-and-forget with retry logic: the gateway sends the webhook and waits for an HTTP 2xx response from the merchant's server. If no 2xx response is received within the timeout window (typically 5–30 seconds), the gateway marks the delivery as failed and schedules a retry. Retry schedules vary by gateway but commonly follow exponential backoff — retrying after 1 minute, then 5 minutes, then 30 minutes, then 2 hours, then 24 hours, before giving up after a defined maximum number of attempts.
Payment Event Types That Trigger Webhooks
|
Event Type |
When It Fires |
Action for Merchant |
|
payment.detected |
Transaction enters mempool (0 confirmations) |
Display 'payment received, awaiting confirmation' to customer |
|
payment.confirmed |
Required confirmation threshold reached |
Trigger order fulfillment — ship, deliver, or activate |
|
payment.expired |
Invoice expiry time passed with no sufficient payment |
Mark order as expired; prompt customer to repay |
|
payment.underpaid |
Payment received but below invoice amount by > tolerance |
Flag for manual review; contact customer for top-up |
|
payment.overpaid |
Payment received above invoice amount by > tolerance |
Apply overpayment handling policy; issue refund if configured |
|
payout.completed |
Outgoing settlement or refund transaction confirmed |
Update accounting records; notify recipient |
|
invoice.cancelled |
Invoice cancelled by merchant via API |
Update order status to cancelled |
Validating Webhook Authenticity With HMAC
Every webhook delivery must be validated before acting on its contents. Validation uses HMAC (Hash-based Message Authentication Code): the gateway computes an HMAC-SHA256 of the raw request body using a shared secret key (provided by the gateway during integration setup), and includes the result as a hex digest in a request header — commonly X-Webhook-Signature or X-Gateway-Signature.
On receipt, the merchant's server recomputes the HMAC using the same shared secret and raw body, then compares it byte-by-byte with the received header value. If they match, the webhook is authentic. If they differ, the request may be fabricated or tampered with and must be rejected. This check must be performed on the raw request body before any JSON parsing, because whitespace differences in the parsed output can produce a different HMAC even for identical semantic content.
Never use the order ID or amount from a webhook to determine whether to fulfill an order without first validating the HMAC signature. A spoofed 'payment.confirmed' webhook is a low-effort attack vector for obtaining goods without payment.
Idempotent Webhook Processing
Gateways may deliver the same webhook event more than once — if the first delivery timed out and was retried, but the merchant's server actually processed it successfully and just returned a delayed response that the gateway counted as a timeout. The merchant's server will then receive two webhooks for the same event.
Idempotent webhook handling ensures that processing the same event twice has the same outcome as processing it once. The standard approach is to store a record of processed webhook event IDs (each webhook should carry a unique event ID in its payload) and check for duplicates before processing. If the event ID is already in the processed set, return 200 without repeating the business logic. This check requires persistent storage — an in-memory cache will not survive a server restart and cannot protect against retries that arrive after a deployment.
Compliance Note: This glossary entry is provided for general educational purposes only and does not constitute financial, investment, legal, or tax advice. Industry terminology may vary across jurisdictions and providers; definitions herein may not directly reflect the specific features, terms, or specifications of Finassets' services. For details on Finassets' offerings, please refer to official product documentation or contact our team directly.