Webhook Notification

A webhook notification is an automatic message that one software system sends to a web address chosen by another system when a particular event occurs. In payments and banking, the sender is usually a payment processor, bank or fintech platform, and the events include a payment succeeding or failing, a refund being issued, a chargeback being opened or an account being verified. The receiver, typically a merchant or partner, processes the message and updates its own records.

Webhooks are the push half of most modern financial APIs. A client calls the provider's API to start something, then waits for webhooks to learn how it ended, because many payment outcomes arrive seconds, hours or days later. Older payment services offered similar callbacks under other names, such as PayPal's instant payment notification (IPN). There is no single legal standard for webhooks; each provider documents its own format, though most use HTTPS and JSON.

Imagine waiting for a parcel. You could phone the courier every ten minutes to ask "has it arrived yet?", which wastes everyone's time. Or you could give the courier your number and ask for a text when it is delivered. The text arrives only when there is news.

A webhook is that text message, sent between computers. A shop's system tells its payment provider, "Here is my address. Let me know when something happens to my payments." When a customer's bank transfer finally clears, or a card payment is disputed, the provider sends a short note to that address saying what happened. The shop's system reads the note and updates the order. Nobody has to keep checking, and the shop hears the news as soon as the provider knows it.

1. Registration. The receiver gives the provider an HTTPS endpoint and chooses which event types it wants, such as "payment.succeeded" or "refund.failed".
2. Event occurs. Something changes in the provider's system, for example an ACH debit returns unpaid.
3. Delivery. The provider sends an HTTP POST to the endpoint with a payload describing the event: an event ID, type, timestamp and the object concerned.
4. Acknowledgement. The receiver replies quickly with a success status code, usually before doing heavy processing.
5. Retries. If no success reply arrives, the provider resends the event on a schedule that backs off over hours or days, then marks it failed.

Because a webhook endpoint is a public address, anyone could send fake messages to it. Common safeguards include:

• Signature checking. The provider signs each payload, often with an HMAC using a shared secret, and the receiver recomputes the signature before trusting the message. Secrets should be changed on a schedule, as described under cryptographic key rotation.
• Timestamps. A signed timestamp lets the receiver reject old messages replayed by an attacker.
• Encryption in transit. Delivery over TLS, sometimes with allow-listed sender IP addresses.
• Idempotent handling. Retries mean the same event can arrive twice. Receivers store event IDs and ignore duplicates, applying the principle of idempotency so that a payment is not credited twice.
• Out-of-order tolerance. Events may arrive out of sequence, so receivers check the object's current status through the API rather than assume order.

Webhooks should not be the only source of truth. Missed messages happen during outages, so well-run firms reconcile webhook data against the provider's reports or API, as part of normal settlement reconciliation.

• Card acquiring. Gateways send events for authorizations, captures, refunds, disputes and payouts, so merchants can ship goods or respond to a dispute within network deadlines.
• Bank transfers and open banking. Payment initiation providers send status changes for account-to-account payments, including rejections that arrive after the customer has left the checkout.
• Issuing and BaaS. Card issuing platforms notify program managers of each authorization, and some let the client approve or decline in real time through a synchronous webhook.
• Onboarding and compliance. Identity verification and sanctions screening vendors post results when a check completes or a match needs review.
• Subscriptions. Providers warn merchants of failed recurring payments so they can contact customers or schedule a payment retry.

Polling, in which the client calls the API repeatedly to ask for status, is simpler to build but wastes capacity and adds delay. Webhooks are faster and cheaper but require the receiver to run a reachable, secure endpoint. Large institutions sometimes prefer message queues or streaming feeds inside private networks, or file-based reporting for bulk data. In bank-to-bank messaging, status reports such as ISO 20022 payment status messages play a similar role, and they rely on an end-to-end transaction reference to tie updates to the original payment, much as a webhook payload carries the provider's object ID.

• Internet Engineering Task Force