Webhooks vs APIs:
Choose How Updates Arrive

Webhooks send event data to a registered URL when a provider’s event occurs. With a conventional HTTP API call, the application requests data or an operation from a service. Choose an API call to ask for information or request a change; choose a webhook to receive event notifications. Use both when a notification should trigger a fresh data lookup.

What is an API, and what is a webhook?#

API stands for application programming interface: the features and rules through which software interacts with other software, according to MDN’s API definition, which includes browser interfaces as well as interfaces to web services. Here, the comparison concerns conventional HTTP API calls and webhook deliveries.

An HTTP API lets an application request the operations the service exposes. In MDN’s HTTP method reference, GET retrieves a resource representation, POST submits data, PUT replaces a resource representation, PATCH applies partial changes, and DELETE removes a resource. An API therefore supports more than checking for updates.

A webhook reverses who initiates the notification: the consuming application registers a receiving URL, the provider sends event data to it when a subscribed event occurs, and the receiver acknowledges the request, as the OpenAPI Initiative explains. OpenAPI also classifies webhooks as a style of API communication.

The useful distinction is a client requesting an operation versus a provider initiating an event notification.

Webhooks vs APIs at a glance#

An API call is not automatically polling. GitHub’s polling guidance describes repeated, scheduled API checks; a single lookup remains a single lookup.

When to use API calls or polling#

Use an API call when the application needs information at a particular moment. GitHub recommends calling its API for information needed only once or intermittently. To request changes, use the API’s corresponding operations, reflected in HTTP methods such as POST, PATCH, and DELETE.

Use polling when repeated checks are necessary and a suitable webhook cannot be used. The schedule must fit both the acceptable delay and the provider’s request allowance. GitHub’s rate-limit documentation shows why a universal polling interval would be misleading: its limits depend on authentication, and some endpoints have stricter limits.

Where polling is necessary, GitHub’s REST API best practices recommend checking only as often as needed, respecting an x-poll-interval header when present, and requesting only required data. GitHub also documents that correctly authenticated conditional requests returning 304 Not Modified do not consume its primary rate limit. That exemption is a GitHub rule; other services need their own documented quota treatment.

When to use webhooks#

Use webhooks when a supported event should initiate processing. GitHub describes near real-time webhook updates and uses such as reacting to code pushes, because notifications start when events occur instead of waiting for a polling check.

Confirm that the provider offers the required event and inspect its payload before choosing webhooks. GitHub recommends subscribing only to necessary events and checking each delivery’s event type and action before processing it.

Near real time does not promise instantaneous, ordered, or successful processing. For example, Stripe documents that delivery order is not guaranteed and events can arrive more than once. Those constraints affect the receiving application’s design.

When to use webhooks and APIs together#

Webhooks and APIs can serve the same workflow: notification starts processing, and retrieval supplies additional data. Stripe distinguishes lightweight thin notifications from snapshot events that include a resource snapshot, which can be stale when processed.

When an action needs the latest state, retrieve the related object through the API after receiving the notification. Stripe recommends fetching the latest resource when a snapshot may be outdated. This makes the webhook a trigger for a current-state lookup.

Event details are a separate requirement: Stripe distinguishes retrieving the latest object from retrieving the complete event, which can contain contextual information and previous attribute values. Retrieve the event when those details are needed; a current-object lookup answers a different question.

Further retrieval is optional when a thin notification’s event type and resource ID provide enough information to process it. The data requirement determines whether an extra API call is necessary.

Delivery failures and the receiving endpoint#

Webhook use includes operating a receiver. The main requirements are authentication, prompt acknowledgement, duplicate handling, and recovery:

• Verify the sender. GitHub recommends HTTPS and validation using a webhook secret. Use the provider’s documented verification mechanism before acting on a delivery.
• Acknowledge promptly. GitHub requires a successful response within 10 seconds and suggests queuing payloads for background processing. Check the actual provider’s response deadline.
• Handle duplicates. Stripe recommends recording processed event IDs and skipping repeated events. Duplicate protection prevents repeated deliveries from being treated as independent work.
• Check the retry policy. Stripe retries failed deliveries for up to three days in live mode, whereas GitHub does not automatically redeliver failed deliveries. Automatic retries are a provider capability, not an inherent webhook guarantee.

Recovery must follow the provider’s available tools. GitHub documents manual redelivery and scheduled API-based checks for failed deliveries, while noting that delivery-history API endpoints are unavailable for some webhook types. Confirm those capabilities before relying on redelivery to repair missed notifications.

The selection follows the information requirement: request data or an operation through an API; receive supported event notifications through a webhook; combine them when notification timing and a subsequent lookup are both required.