Webhook

A webhook is an HTTP callback: instead of repeatedly checking for a result, the server sends a POST request to a URL the moment an event happens.

What It Is

Generative media APIs — the ones that turn a text prompt into an image or video — rarely respond right away; a render can take seconds to over a minute. The obvious approach is polling: asking the API “is it ready yet?” on a repeating timer, which burns requests on every “no” answer and adds a delay equal to the timer interval. A webhook flips the relationship: instead of the client asking, the server tells, calling a registered URL automatically the instant the job is done — the difference between phoning a restaurant every few minutes about a delivery and giving them a number to text when the order leaves the kitchen.

Mechanically, a webhook is an HTTP POST the API server sends to a URL the client controls, carrying a payload that describes the event, an ID, and a timestamp. Because that URL is public, the receiving server verifies a cryptographic signature on every payload — typically a hash of the raw body computed with a shared secret, checked with constant-time comparison so it can’t leak through timing; some providers sign asymmetrically instead, against a published public key. This payload-signature-timestamp-ID shape has converged into something close to an industry standard — the Standard Webhooks specification — adopted by providers from OpenAI and Anthropic to Twilio and PagerDuty, according to Standard Webhooks.

Delivery is never guaranteed on the first attempt: a receiving server can be down, slow, or mid-deploy, so providers retry failed deliveries on a schedule. That means a webhook handler must be idempotent, since the same event can arrive twice when a retry follows a first attempt that actually succeeded — which is also why an integration is never “fire and forget”: the endpoint must stay reachable, respond quickly, and do its real work asynchronously rather than inside the request.

How It’s Used in Practice

The most common place to run into webhooks today is integrating an async generation API. fal.ai, for example, lets a client pass a webhook URL in the same request that submits the job, so the calling server never holds a connection open or polls while a video renders. According to fal Docs, fal.ai attempts initial delivery within about 15 seconds of completion and retries a non-responsive endpoint up to 10 times over roughly two hours, checking the signature against a published key with a tight timestamp window to block replayed requests.

Multi-provider setups raise the bar further: a product that can route a job to more than one backend needs one webhook receiver that normalizes each provider’s payload shape into a single internal event format, rather than a separate handler per provider.

Pro Tip: Build the webhook receiver to be idempotent before you build anything else. Store the event ID the first time you see it and skip processing if it shows up again — every webhook integration eventually receives the same event twice, usually right when traffic is highest.

When to Use / When Not

Common Misconception

Myth: Webhooks guarantee delivery, so a handler doesn’t need to plan for failure. Reality: Webhook delivery is at-least-once, not exactly-once. Providers retry on failure or timeout, which means the same event can arrive more than once — a handler that isn’t idempotent treats a retry as a brand-new event and duplicates the result.

One Sentence to Remember

A webhook turns a slow, asynchronous API call into a notification instead of a chore: register the URL once, verify every signature before trusting the payload, and build the handler to survive receiving the same event twice.

FAQ

Q: How is a webhook different from polling? A: Polling means the client repeatedly asks the API if a job is finished. A webhook flips it: the API calls the client’s URL automatically the moment the job completes, with no repeated requests needed.

Q: Do webhooks need authentication? A: Yes. Since webhook URLs are public, providers sign each payload with a secret or private key. The receiver verifies that signature before trusting the data, blocking forged requests from third parties.

Q: What happens if my server is down when a webhook fires? A: Most providers retry failed deliveries on a schedule for a limited window, then give up. That’s why webhook handlers must be idempotent — safely processing a duplicate delivery without errors.

Sources

• Standard Webhooks: Standard Webhooks Specification - Industry-wide spec defining the common webhook payload, signature, and ID format
• fal Docs: fal.ai Webhooks - Real-world webhook implementation for async generative media jobs, including retry and signature verification details