API retry safety route: idempotency, webhooks, and 429 handling

A webhook and a callback are often explained with the same sentence: "one system calls another system later." That sentence is not wrong, but it hides the part that matters during integration work: who owns the call, when it happens, and what failure means.

## Short distinction

A callback is a broad programming pattern. You give another piece of code, library, or service a way to call you back later. In a local program, that may be a function. In a browser flow, it may be a redirect URL. In an API integration, it may be an endpoint.

A webhook is a specific network pattern. Service A sends an HTTP request to Service B when an event occurs. The receiving URL is usually registered in advance, and the sender decides when to call it.

So the practical rule is:

- Callback describes the relationship: "call me when you are done."
- Webhook describes the transport and event delivery shape: "send an HTTP event to this URL."

## The caller is the main clue

If your application calls an API and waits for the response, that is an ordinary request. If your application passes a callback URL and the provider later calls that URL, the provider becomes the caller at the important moment.

That reversal changes the checklist. Your server must be reachable from outside. It must answer quickly. It must handle duplicate delivery. It must verify that the request came from the expected sender. It must not assume the user is still sitting on the same page.

## Callback URL is not always a webhook

A callback URL can mean several things:

- OAuth redirect URL after login or consent.
- Payment return URL after the user leaves a checkout page.
- Webhook endpoint for asynchronous status updates.
- File processing completion endpoint.

The confusing part is that product screens often label all of these as "callback URL." A better integration note should say what calls the URL, what event triggers it, whether it is user-facing or server-to-server, and whether retries can happen.

## Failure handling differs

With a webhook, the sender usually expects a fast HTTP success response. A 200 or 204 means "received," not necessarily "fully processed." If the receiver needs slow work, it should store the event, return quickly, and process it in the background.

If the receiver returns 500, times out, or drops the connection, many webhook providers retry. That is helpful for reliability but dangerous for systems that treat each request as unique. The receiver should store a provider event ID, use idempotency, and make duplicate events harmless.

With an OAuth-style callback URL, retry behavior may not exist. The browser may simply show an error or the user may need to restart the flow. That is why documentation should avoid using "callback" alone when the runtime behavior matters.

## Security checklist

For webhooks, expect these controls:

- Signature verification using a shared secret or public key.
- Timestamp tolerance to reduce replay risk.
- Event ID storage for deduplication.
- Strict content type and schema validation.
- Least-privilege endpoint behavior: receive, verify, enqueue, respond.

For redirect callbacks, expect a different checklist:

- Exact redirect URL allowlist.
- State parameter validation.
- Short-lived authorization code exchange.
- No sensitive tokens in logs or query strings beyond the intended protocol.

## Naming rule for docs and UIs

When a form asks for "callback URL," add one sentence beside it:

"We will send a POST request to this URL when the payout status changes."

or:

"The user's browser will return to this URL after authorization."

That one sentence prevents a large class of integration mistakes. It names the caller, the method, the trigger, and the runtime boundary.

## Working example

Payment status update:

1. Your service creates a payment.
2. The provider returns a payment ID.
3. Later, the provider sends POST /payments/webhook to your server.
4. Your server verifies the signature.
5. Your server stores the event ID.
6. Your server returns 204.
7. Your worker updates the order status.

That is a webhook. It may also be documented as a callback endpoint, but "webhook" is the more precise term because the key behavior is an event-driven HTTP delivery from the provider to you.

## Reusable rule

Use "callback" when describing the broad promise that another component can call you later. Use "webhook" when the later call is an HTTP event sent by another service to your registered endpoint. If a screen or document says only "callback URL," ask four questions before shipping: who calls it, what method is used, what event triggers it, and what happens on failure.

Webhook vs callback: who calls whom, and when?

// COMMENTS

ON THIS PAGE