A webhook lets one system notify another when an event occurs. Polling means calling an API repeatedly to check whether something has changed. Both can be part of the same integration: the webhook announces a change, and an API request retrieves details or checks the current state. “Webhook vs. API” therefore needs a more precise question: how should this product learn that something has happened?
The answer affects how long a customer waits, how many requests the integration makes and how it recovers when a message is delayed. Payment confirmation is a useful example because the difference becomes visible to the customer: a payment may have completed while the shop still shows the order as pending.
An API request and a notification start in different places
In a typical HTTP API interaction, an application sends a request to a service and receives a response. It might ask for an order’s current status or request the creation of a payment. An endpoint is the address at which the service accepts a particular kind of request. The application calling it decides when to ask, within the service’s rules and access limits.
With a webhook, the system producing an event sends a request to an endpoint provided by the receiving application. A payment provider can notify a shop’s backend when a payment succeeds, instead of waiting for the shop to ask again. The receiver needs to verify and process the notification. A webhook is itself usually delivered through an HTTP request; it does not replace the entire API.
The two mechanisms also serve different purposes within a transaction. An API request can initiate the payment, while a webhook reports a later outcome. GitHub documents another example: a repository event can notify an external service and trigger work there. In either case, the available event types and delivery rules depend on the provider.
One pending payment, two ways to discover its outcome
Consider a hypothetical checkout at Mercato, a commerce platform. Its backend creates a payment through the provider’s API, stores the payment reference against the order and receives a pending result. The customer sees that the payment is being processed. The backend now needs to find out when that state changes without treating “pending” as either failure or success.
With polling, Mercato schedules repeated requests for the payment’s current status. If it checks every thirty seconds in this example, a change just after one check will normally remain undiscovered until the next successful check. Network delays, rate limits and failures can extend that interval. Increasing the frequency may shorten the wait, but also increases requests, including requests whose answer has not changed.
With a webhook, the provider sends a notification when the relevant event occurs. Mercato verifies it, associates it with the stored payment and updates the order. This can reduce the delay without repeated status checks for every payment, but the notification still has to be delivered and processed. It is not a promise that the screen will update instantly.
The customer’s browser is a separate part of this flow. A provider webhook normally reaches a backend endpoint, not the customer’s open page. Mercato must also decide how the page learns about the updated order, for example by checking Mercato’s backend while the payment is pending. That browser-side polling is different from having the backend repeatedly query the external payment provider.
Compare polling and webhooks against the product requirement
| Decision | API polling | Webhook notification |
|---|---|---|
| Who starts the exchange? | The application that wants to check the state. | The system that reports an event. |
| What determines the delay? | The checking interval, plus response time and any failures. | Event creation, delivery and processing time, including retries. |
| What creates traffic? | Scheduled requests, including checks with no new result. | Subscribed events and possible repeated deliveries. |
| What must the receiver operate? | A schedule, API access and handling of errors and limits. | A reachable endpoint, delivery verification and reliable event processing. |
| What does it tell the product? | The state returned when the query is processed. | Information about an event; a further API query may be needed. |
Polling can be appropriate when no suitable webhook exists, when updates are infrequent or when the permitted delay makes scheduled checks sufficient. A daily back-office synchronization has different requirements from a customer waiting at checkout. The decision also depends on whether the provider permits the required volume of calls and whether the receiving system can operate a webhook endpoint.
A hypothetical calculation makes the traffic trade-off visible: checking 1,000 pending payments once per minute creates about 1,000 status requests per minute if each payment requires a separate call. Batch endpoints, fewer pending payments or a slower interval would change that number. It is an example for sizing the integration, not a measurement or a claim about every provider’s limits.
Delivery failures belong in the payment journey
A webhook can be delayed, delivered more than once or arrive after a related event. The provider’s documentation defines the actual guarantees and recovery options. Stripe, for example, documents duplicate deliveries and does not guarantee event ordering. A receiver should therefore not assume that the last notification to arrive describes the latest state.
In Mercato’s example, a repeated success notification must not send the same order to fulfilment twice. The team needs processing rules that make repeated delivery safe, including identifying processed events and guarding the business operation itself. This property is called idempotency: repeating the same operation does not produce an additional effect. An event identifier helps detect repeat deliveries, but the order’s own processing rules also matter.
That is separate from retrying the API request that creates a payment. Some providers accept an idempotency key so that a retry can be recognized as the same request. Stripe documents this mechanism and its limits. A duplicate-safe webhook handler does not, by itself, prevent two separate payment-creation requests from charging a customer twice.
The receiver must also check where the notification came from before changing an order’s state. Providers may offer signed notifications; Stripe documents signature verification and checks against replayed messages. The product requirement is that an untrusted incoming request cannot mark an order as paid. An API key used to call a provider and the secret used to verify its webhook may be different credentials.
Recovery can combine notifications with API queries
Mercato can use webhooks for normal payment updates and a scheduled recovery process to investigate payments that remain pending longer than expected. That process can query the provider’s API and reconcile the local record with the authoritative payment state. Its frequency should account for the payment methods involved: a legitimately slow payment must not be classified as an incident simply because it takes longer than a card transaction.
The recovery policy needs to describe what happens if the webhook endpoint is unavailable, whether the provider retries and how missed events can be found or replayed. It also needs to distinguish successful receipt from completion of the business work. An endpoint may acknowledge a notification after accepting it into a durable queue and process it later; monitoring only delivery responses would miss a stalled worker.
For the customer, the resulting requirement might be a pending-payment screen with a safe way to check progress and a support route when the expected wait is exceeded. The exact wording and timing depend on the payment method. Showing a failure message simply because a notification has not arrived can encourage a second payment attempt while the first one is still being resolved.
Decisions to record before implementation
The integration brief should state how quickly the product needs to learn about a change and which system holds the authoritative state. Those requirements give Engineering a basis for choosing the normal update path and its recovery process. The review can then address concrete cases:
- Which provider events are needed, and do they include enough information to update the order?
- How will the receiver verify notifications and associate them with the right customer and payment?
- What prevents duplicate or out-of-order messages from triggering an incorrect business action?
- How will delayed or missed updates be detected, investigated and recovered?
- What will the customer see while the outcome remains uncertain, and what can support check?
The guide to APIs for Product Managers covers the wider request-and-response model. For the effect of repeated checks on request budgets, read API rate limits. The annotated checkout architecture diagram places the frontend, backend and provider in the same flow.
The book APIs for Product Managers develops integration decisions, permissions and error handling in more detail.
Technical references
- GitHub: how webhooks differ from polling an API.
- Stripe: webhook delivery, verification and event processing.
- Stripe: idempotent API requests and retry behaviour.
