HTTP Callback

An HTTP callback is an HTTP request that a server sends to a URL you specified, typically to notify you that an event occurred or an operation completed. You give the server a URL up front, and when the time comes, it calls you back at that URL with the result. The term comes from the same concept as callbacks in programming — instead of waiting for a return value, you provide a function (or in this case, a URL) to be invoked later.

Callback vs webhook

The terms get used interchangeably, but there's a subtle distinction. A webhook is a specific pattern of callback: it's event-driven, usually POST-based, and fires automatically whenever a defined event occurs in the source system. A callback is the broader concept — any HTTP request sent to a client-specified URL in response to something.

• Webhook — Stripe sends a POST to your URL every time a payment succeeds. You registered once, and it fires indefinitely on every matching event.
• Callback — you submit a video for transcoding and include a callback_url parameter. The service POSTs to that URL once when the transcoding finishes. It's a one-time notification tied to a specific operation, not a recurring event subscription.

In practice, most developers treat them as synonyms. The distinction matters mainly when designing APIs — if the notification is per-request, call it a callback. If it's a persistent subscription to events, call it a webhook.

Synchronous vs asynchronous callbacks

In HTTP, "synchronous callback" is a bit of a misnomer — HTTP itself is request-response, so there's no true synchronous callback like you'd have in-process. What people usually mean:

• Synchronous (redirect-based) — the server redirects the user's browser to your callback URL as part of the same flow. OAuth redirect URIs work this way: the user authenticates, and the authorization server redirects the browser to your redirect_uri with an authorization code in the query string. The "callback" happens in the same user session.
• Asynchronous (server-to-server) — the server sends an HTTP request to your callback URL at some later time, independent of any user session. Payment completion callbacks, job processing notifications, and webhooks all fall into this category.

Callback URLs and registration

There are two common patterns for telling a service where to call back:

• Per-request callback — you include a callback_url or webhook_url parameter in each API request. The service uses that URL to notify you when the specific operation completes. Common in file processing, transcoding, and batch APIs.
• Pre-registered callback — you configure the URL once in a dashboard or via an API, and the service uses it for all future events. This is the standard webhook model used by Stripe, GitHub, and most SaaS platforms.

For per-request callbacks, the URL is typically validated when the request is made. For pre-registered callbacks, most providers send a verification request (a challenge or test event) to confirm you control the URL before activating it.

Common callback patterns in APIs

Payment processing

You initiate a payment and the processor calls back to confirm success or failure. Stripe uses webhooks (persistent subscriptions), while PayPal's older IPN system sends per-transaction callbacks. In both cases, the callback carries the transaction result in the payload.

OAuth redirect URIs

After the user authenticates with the identity provider, their browser is redirected to your redirect_uri with an authorization code. This is a synchronous, browser-based callback. The URL must be pre-registered to prevent open redirect attacks.

Long-running operations

APIs that process large files, run reports, or perform batch operations often accept a callback URL. The initial request returns 202 Accepted with a job ID. When processing finishes — seconds or hours later — the service POSTs the result to your callback URL. This avoids the client having to poll a status endpoint repeatedly.

CI/CD and build systems

Build services call back to source control providers with the build status. GitHub's commit status API and GitLab's pipeline webhooks both use this pattern — when a build finishes, the CI system sends a callback to update the commit status.

Handling callbacks reliably

Whether you're receiving a one-off callback or a persistent webhook, the same principles apply:

• Return 200 quickly — acknowledge receipt before doing heavy processing. If the work takes time, queue it and respond immediately. If you exceed the sender's timeout, they'll treat it as a failure.
• Handle duplicates — the sender may retry if they don't get a response, so your handler must be idempotent.
• Verify the source — check the request signature, validate the callback origin, or verify the data with a server-side API call before trusting it.
• Use HTTPS — callback payloads often contain sensitive data. Always register HTTPS URLs.

FAQ

What is an HTTP callback?

An HTTP callback is an HTTP request that a server sends to a URL you specified, notifying you that an event occurred or an operation completed. You provide the URL up front, and the server "calls back" to it when there's something to report.

What is the difference between a callback and a webhook?

A webhook is a type of callback. Callbacks are the broad concept — any HTTP request sent to a client-specified URL. Webhooks are specifically event-driven, persistent subscriptions where the server notifies you every time a particular event occurs. A one-time "notify me when this job finishes" URL is a callback. A "notify me every time a payment succeeds" subscription is a webhook.

How do I register a callback URL?

It depends on the API. For per-request callbacks, you include a callback_url parameter in your API request. For persistent webhooks, you register the URL in the provider's dashboard or via their API. Either way, the URL must be publicly accessible over HTTPS and should return a 200 status code quickly when called.

HTTP callbacks are the foundation of webhooks — every webhook is a callback triggered by an event. The data arrives in the request payload, and your endpoint should respond within the sender's timeout to avoid retries. When receiving callbacks from external services, always verify the status code you return and consider checking signatures to confirm authenticity.