Webhook vs API: what's the difference?

An API call is your code asking a server for something and getting the answer back. A webhook is the server calling a URL you gave it when something happens. They aren't alternatives: a webhook is itself an HTTP request, sent in the other direction, and the two work together. You call the API to start the work, and a webhook, or polling, tells you when it's done.

Sume's behavior below comes from its Runs and results, Jobs and results, Webhooks and Run webhooks docs, and the WebSocket definition from MDN's WebSocket API page. All were read on 2026-09-28.

What is the difference between a webhook and an API?

The difference is who starts the request. With an API call, your code sends the request when it wants something: create a job, read its status, fetch a result. With a webhook, the provider sends the request when an event happens, such as a job finishing. You don't ask; you're told.

For long jobs, that changes what your code does while it waits. Sume's run docs compare the two ways to learn that a run finished, and they carry the identical receipt. The docs' advice for production is to do both: the webhook is the fast path, and a read of result_url is the backup for the day your endpoint is down.

Is a webhook an API?

In a sense, yes. A webhook is an HTTP request, such as Sume's signed POST with a JSON body, that the provider sends to an endpoint you run. Your endpoint is a small API that you host and the provider calls. The provider decides the payload and when to send it; you choose the URL and decide what counts as a valid request.

That reversal is why a webhook endpoint needs its own checks. Anyone can send a request to a public URL, so a receiver verifies a signature before it trusts the body. Sume signs each delivery with HMAC-SHA256 over <timestamp>.<raw_body> and sends it in x-sume-webhook-signature as sume-v1=<hex_signature>.

When should I use a webhook instead of calling the API?

Use a webhook when the work outlasts a request and you don't want a loop per job. Video generation is one: Sume's docs say video jobs routinely outlast the 30 seconds a submit can wait. On Sume, a submit returns the job or run id in its first response, and a 2xx means paid work is in flight, not that it finished. Add a webhook URL and Sume POSTs one terminal event to it, with no progress events in between: for a Format run when the run completes or fails, for a generation job when the job completes, fails or is canceled.

Keep polling as the fallback. The docs call a webhook a delivery optimization, not your only recovery path, and a failed delivery never changes the run or job itself. Sume Format run lifecycle covers both paths for runs. This create asks for a webhook and still gets polling URLs back:

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-promo-v1" \
  -d '{
    "input": { "product_url": "https://example.com/p/8823" },
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

What does a webhook endpoint need?

Four things, whoever sends the webhook: a public HTTPS URL, a signature check on the raw body before any JSON parse, a fast 2xx, and deduplication, because a retry repeats the same event. On Sume, localhost, private-network and non-HTTPS webhook URLs are rejected with 400 invalid_request, so test on your machine through a tunnel, as in Test Sume webhooks locally. Webhook security best practices walks through each check.

Where do WebSockets fit in?

A WebSocket is a third pattern: a two-way session between a browser and a server, in which the client can send messages and receive responses without polling for a reply. Sume's Developer API has no SSE or WebSocket transport today, and GET /v1/jobs/:id/events is a pull snapshot, not a stream. To get a finished job to a browser, take the webhook on your server and pass it on the way your app already talks to the page. Long polling vs short polling compares the ways a client can wait.