Webhooks vs APIs is a common comparison, but the two are not opposites. An API is an interface software uses to interact with another system. A webhook is usually a way for one system to notify another by sending a request when an event happens. A webhook receiver can itself be an HTTP API endpoint.
For a business integration, the useful choice is how a particular update should be discovered and completed. The answer might combine notifications, requests for current data and periodic reconciliation. Choose against the available interfaces and required behaviour rather than a blanket rule that push is always better than pull.
Separate requests, notifications and polling
In an HTTP request/response exchange, one participant sends a request and receives a response. MDN's HTTP overview explains that foundation. The business purpose of the exchange determines whether it is a status lookup, a command or a webhook notification.
| Pattern | Example use | Question to settle |
|---|---|---|
| On-demand API request | Fetch current delivery status when staff open a job | What happens when the source is unavailable? |
| Polling | Check for changed deliveries on a schedule | How are gaps, pagination and repeated records handled? |
| Webhook | Receive notice that delivery status changed | How are duplicate, delayed or missing notices handled? |
| Combined approach | Receive a notice, retrieve required data and reconcile later | Which record is authoritative and who resolves discrepancies? |
Not every provider supports every pattern. Inventory the actual API, event types and access conditions before designing around a notification that does not exist.
Start with the business freshness requirement
Ask how quickly a change needs to affect the next task and what happens if it arrives later. A finance export reviewed tomorrow has a different requirement from a customer waiting for a payment decision. Avoid selecting infrastructure from a vague request for everything to be “real time”.
State the tolerated delay, visible pending state and escalation condition. A webhook can reduce waiting for a scheduled check, but transport and processing can still be delayed. Polling can provide a useful known schedule, but it needs to respect the source's access and usage constraints.
Trace an order update through a combined design
Imagine a fictional supplier connecting an order system to a customer portal. The order system is authoritative for dispatch status. The portal displays a synchronised view with an update time, and a background process receives supported change notifications.
A notification identifies an affected order. The integration checks its authenticity under the provider's contract, records the event appropriately and fetches current details if needed. It applies an allowed update without repeating a completed business action. The exact sequence depends on the provider's event format and consistency rules.
A reconciliation task then checks the source for changes the portal has not successfully applied. Its purpose is repair and confidence in completeness, not a second uncontrolled way to create the same dispatch or invoice.
Plan for duplicate and out-of-order delivery
Provider behaviour matters. For example, Stripe documents duplicate events and does not guarantee event delivery order. That is a concrete contract to design for when using Stripe, not proof that all providers share identical retry windows or identifiers.
For any chosen provider, determine how events are identified, how repeated delivery differs from a distinct later change and how the current business state is obtained. The existing webhook retries and idempotency guide goes deeper into preventing repeated effects. Keep this architecture decision linked to that operational detail.
Protect the boundary and validate the request
Agree authentication, signature verification where supported, event schema and allowed record scope. Use the provider's current documentation and test fixtures. A request containing a familiar order number is not sufficient evidence that it came from an authorised source.
Keep credentials server-side as appropriate to the selected interface. Decide what is logged, who can inspect it and how sensitive data is handled. Test malformed input and unauthorised records without using live customer data for a public demonstration.
Design recovery before choosing the simplest demo
For polling, examine changed-since filtering, stable pagination, deletions and the point at which progress is saved. For notifications, examine acknowledgement, retries, replay and event history. Confirm what the provider actually offers rather than inventing a repair API.
Give unresolved updates an owner, visible status and controlled retry path. Include the case where the source accepted an action but the integration lost the response. Recovery must not blindly repeat an operation merely because the caller did not see success.
Compare the cost of useful completion
Estimate expected event or polling volume, source limits, processing, storage and staff investigation. Use real traffic evidence if available, and otherwise label assumptions. A webhook architecture may need queues and monitoring; a polling design may make many unnecessary requests or miss a required deadline.
Compare both against the business freshness and recovery requirements. The cheapest transport pattern does not necessarily produce the lowest operating cost when missed or duplicated business actions need manual repair.
Write integration acceptance scenarios
- A normal change reaches the destination within the agreed behaviour and shows the correct source record.
- Repeated delivery does not repeat the same completed business effect.
- A late update cannot incorrectly reverse a newer authoritative state.
- A source outage or usage limit creates a visible recoverable condition.
- Reconciliation detects and addresses a deliberately omitted update in a safe test environment.
Bring these scenarios and the source documentation to an API integration discussion. The integration requirements guide covers the broader contract. Select the pattern that meets that contract, including how an operator can tell when it has failed.
