What is Webhook?

What Is a Webhook?

A webhook is an automated notification sent from one system to another when something specific happens. Instead of your system constantly asking "has anything changed?" (which is called polling), a webhook flips the model around -- the other system tells your system when something happens, the moment it happens.

Here is a simple analogy. Imagine you are waiting for a parcel. You could check the front door every five minutes to see if it has arrived (that is polling). Or you could install a doorbell, and the delivery driver presses it when the parcel arrives (that is a webhook). The doorbell approach is obviously more efficient -- you only take action when there is actually something to act on.

In the payments world, webhooks are the mechanism by which payment providers tell your system about events in real time. A payment was successful. A recurring charge failed. A customer disputed a transaction. A refund was processed. Each of these events can trigger a webhook notification that your system receives and acts on automatically.

How Webhooks Work

The mechanics of a webhook are surprisingly straightforward:

Setup

You register a webhook URL with the service provider (in this case, your payment provider). This URL is an endpoint on your server -- essentially a web address that your system is listening on, ready to receive incoming messages. Most payment providers let you configure which events should trigger webhook notifications, so you only receive the ones you care about.

Event Occurs

Something happens in the payment provider's system -- a charge is completed, a payment fails, a subscription is cancelled, a dispute is opened. The provider detects this event and prepares a webhook notification.

Notification Sent

The payment provider sends an HTTP POST request to your webhook URL. The body of this request contains data about the event -- typically in JSON format -- including details like the event type, the transaction ID, the amount, the timestamp, and any other relevant information.

Your System Responds

Your server receives the webhook, processes the data, takes whatever action is needed (updating a database, sending a confirmation email, triggering a fulfilment process), and sends back a response to the payment provider acknowledging receipt. This response is usually a simple HTTP 200 status code meaning "got it."

Retry Logic

If your server does not respond (maybe it is temporarily down or overloaded), the payment provider will typically retry the webhook several times over a period of hours or days. Retry schedules vary by provider, but the general pattern is that retries become less frequent over time -- the first retry might be after a few minutes, the next after an hour, and so on.

Why Webhooks Matter in Payments

Webhooks solve several important problems in payment processing:

Real-Time Updates

Without webhooks, your system would need to periodically check the payment provider's API to find out what has happened. This polling approach wastes resources (most checks will return no new information), introduces delays (you only find out about events at your next poll interval), and puts unnecessary load on both your system and the provider's API. Webhooks eliminate all of this by delivering updates instantly.

Handling Asynchronous Events

Many payment events do not happen at the point of sale. A customer might dispute a transaction days or weeks later. A subscription renewal might fail because the card expired. A refund might take several days to process. Webhooks let your system stay informed about these events as they happen, without needing a human to check manually.

Automating Business Processes

Webhooks are the trigger mechanism for automation. When a payment webhook fires, your system can automatically update the customer's account status, send a receipt or confirmation email, trigger shipping or fulfilment, update your accounting records, alert your team if something needs attention, or retry a failed payment after a delay. Without webhooks, all of these actions would require either manual intervention or constant polling -- both of which are inefficient and error-prone.

Common Payment Webhook Events

Most payment providers offer webhooks for a standard set of events. While the exact naming varies, common ones include:

• payment.completed -- A payment was successfully processed
• payment.failed -- A payment attempt was declined or failed
• payment.refunded -- A refund was issued
• subscription.created -- A new subscription was set up
• subscription.cancelled -- A subscription was cancelled
• subscription.payment_failed -- A recurring subscription payment failed
• dispute.created -- A customer has disputed a transaction
• dispute.resolved -- A dispute has been resolved (won or lost)
• payout.completed -- Funds have been settled to your bank account

Security Considerations

Because webhooks involve receiving data from an external source, security is critical. You need to be confident that the webhook actually came from your payment provider and was not spoofed by a malicious third party. Most providers address this through webhook signatures -- each webhook request includes a cryptographic signature that your server can verify using a shared secret key. Always verify webhook signatures before processing the data.

Other security good practice include using HTTPS for your webhook endpoint to encrypt data in transit, validating the payload structure before processing it, implementing rate limiting to protect against webhook flooding, and never trusting webhook data for sensitive operations without cross-referencing it against the payment provider's API (for example, if a webhook says a payment was successful, confirm this via the API before shipping goods).

Relevance to Telephone and Phone Payments

Webhooks are every bit as important for phone payments as they are for online payments. When a customer makes a payment over the phone using a secure payment platform, the transaction generates the same kinds of events that online payments do -- and webhooks deliver real-time notifications about those events.

For businesses that handle phone payments, webhooks enable several valuable workflows. When a phone payment is completed, a webhook can trigger the agent's screen to update with a payment confirmation, eliminating the need to manually check whether the transaction went through. If a phone payment fails, a webhook can alert the agent immediately so they can ask the customer to try a different card. After the call, webhooks can trigger automated confirmation emails or SMS messages to the customer, create entries in the CRM, and update billing records -- all without manual data entry.

This is particularly valuable in contact centre environments where agents handle high volumes of calls. Without webhooks, agents would need to manually check transaction statuses, update records, and send confirmations. Webhooks automate all of this, letting agents focus on the customer rather than on data entry.

Practical Considerations

• Always verify webhook signatures to ensure the notification genuinely came from your payment provider
• Build your webhook handler to be idempotent -- if the same webhook is delivered twice (due to a retry), your system should handle it gracefully without duplicating actions
• Respond to webhooks quickly (within a few seconds) with a 200 status code, then process the data asynchronously if needed. Slow responses may cause the provider to retry unnecessarily
• Log all received webhooks for debugging and audit purposes
• Set up monitoring to alert your team if webhook delivery fails or if your endpoint stops responding
• Have a fallback mechanism (such as periodic API polling) for critical processes, in case webhook delivery is disrupted
• Keep your webhook endpoint's processing logic simple and solid -- a crash in your webhook handler can cause cascading failures across your payment workflow
• Test your webhook integration thoroughly, including failure scenarios and retry behaviour

Webhooks are one of those technologies that work best when you do not notice them. When they are set up properly, information flows smoothly between your payment provider and your business systems, events are handled automatically, and your team stays informed without lifting a finger. When they are not set up properly -- or not set up at all -- you end up with manual processes, delayed information, and missed events. For any business that takes payments, investing in solid webhook integration is time well spent.