A webhook lets a service notify your application about an event. With a request-based HTTP API, your application initiates a request to read or change something. The practical comparison is usually event notification versus requesting information, not webhook versus every kind of API.
API is the broader term: it means an interface through which software interacts. APIs are not limited to pulling data, and a webhook receiver is itself a programmatic interface. MDN's API definition explains that broader meaning.
The two approaches often work together. A webhook can announce a change; an API request can then retrieve the current record or perform the next action.
The difference in one table
| Question | Request-based HTTP API | Webhook |
|---|---|---|
| Who starts the exchange? | Your application sends a request | The provider sends an event notification |
| What prompts it? | A user action, scheduled job or other application logic | An event the provider supports |
| Typical use | Read a record, create an order, update a field | Notify your system that a payment or status changed |
| Do you keep asking for changes? | You do if you use polling | Not for each event notification |
| What must be checked? | Operations, permissions, limits and error behavior | Events, payloads, authentication and delivery policy |
Both involve requests and responses at the HTTP level: a webhook receiver also sends a response to the provider. “Push” describes who initiates the notification, not a connection with no response at all.
How a webhook works
You configure a receiving URL and subscribe to the events you need. When a supported event occurs, the provider sends a request, commonly an HTTPS POST, to that URL.
For example, a payment notification might trigger an order-status update. This is an illustrative sequence:
The provider records a payment event.
It sends a notification to your registered endpoint.
Your receiver checks that the request is authentic and relevant.
The event is accepted for processing, and your application applies the appropriate business action.
Delivery need not be instantaneous. A request may be delayed, fail, or be retried according to the provider's policy. Some payloads contain the relevant record, while others mainly identify what changed and require a follow-up API request.
When an API request or polling fits
An API request is useful when your application needs to act now: retrieve a customer's details, create a record, or update a setting.
Polling means repeating a request to look for changes. Consider it when the provider has no suitable webhook, when a scheduled refresh meets the business need, or when you need a separate check for missed updates. Its frequency must fit the provider's limits and your acceptable delay.
A daily reporting job and a time-sensitive order workflow need different update schedules. Choose the mechanism around the task rather than assuming that faster is always necessary.
When a webhook fits
A webhook is useful when the provider exposes an event your system needs to react to. It avoids repeatedly asking for that event, but you still need a reachable receiver and a plan for failures.
Before choosing it, check whether the event actually represents the state you need. “Record updated” may require inspecting the record; “request accepted” may not mean processing is complete.
| Your requirement | Starting point |
|---|---|
| Fetch a record when a user opens a screen | API request |
| Submit a change to the source system | API request |
| React to a supported external event | Webhook |
| Import records created before the connection existed | API or supported export/import |
| Check that important records have not drifted | Scheduled comparison using available records/API |
| Keep an interactive client connected for ongoing messages | Consider WebSocket support |
Where WebSockets fit
WebSocket is a protocol for a persistent connection through which either side can send messages after the connection is established. It can support interactive features such as chat or live collaboration. It is not a category outside APIs: browsers expose a WebSocket API. See MDN's WebSocket documentation.
A webhook is a separate event-triggered HTTP delivery to a registered endpoint. A WebSocket connection supports ongoing messages while connected. Neither mechanism alone provides durable history or recovery after a disconnect; those are application and provider responsibilities.
This distinction helps choose a transport. It does not require turning an event-notification workflow into a persistent connection.
Delivery guarantees come from the provider
Do not assume that every webhook retries automatically or that every event arrives exactly once. Stripe documents retries, duplicate events and ordering considerations. GitHub states that failed webhook deliveries are not automatically redelivered. These are different provider policies.
“At least once,” when a system offers that guarantee under defined conditions, allows duplicates while promising at least one delivery within those conditions. It does not mean “the event might never arrive.” A webhook label alone establishes no such guarantee, and finite retry attempts can still end with an undelivered event.
For a critical workflow, establish who identifies missed work and how it can be recovered.
What a reliable receiver needs
The implementation should match the provider and the importance of the event. A useful review covers four areas:
Authenticity. Verify requests using the provider's supported method. A public URL is not proof of the sender. GitHub's delivery validation guide describes its signature-based approach.
Acceptance and processing. For queued processing, validate the request and durably record the accepted work before acknowledging it. A successful receipt response should not be confused with completion of all downstream work. Keep slow processing out of the receiver's response path where appropriate; GitHub's webhook practices discuss asynchronous handling.
Repeated effects. Repeated notifications should not create the same order twice. Deduplicate using suitable identifiers and make processing safe to repeat. Sending an idempotency key helps only where the receiver implements that behavior; Stripe's request idempotency documentation describes one provider's implementation.
Recovery. Track failed processing separately from failed delivery. Decide how to replay accepted work, handle stale events, and compare important records with the source. Do not rely on a notification stream as the only history unless the provider actually supplies the required guarantees.
These checks do not turn a webhook into a promise of exactly-once business processing. They make the failure cases explicit and testable.
Choose the connection around your workflow
Describe the event or data you need, the acceptable delay, and the consequence of a missed or repeated update. Those answers guide the implementation.
For a business-system example, see CRM integration. For budgeting, see API integration cost.