Sume webhook_url without a mode field: it runs in webhook mode

If you send webhook_url (or its alias callback_url) and leave out mode, Sume runs the job in webhook mode. If you omit both, you get async. In webhook mode the submit returns 202 with the job envelope and poll URLs, and Sume stores the callback and posts a signed terminal event to it.

The four modes

The Jobs and results page compares the modes. The mode decides how you learn the outcome. It never changes whether a job is created, its cost, or its run time.

A submit with no mode

This request names no mode. The presence of webhook_url selects webhook mode. The URL must be public HTTPS. The API rejects localhost, private-network, and non-HTTPS URLs, so test with polling or a tunnel.

curl -X POST https://api.sume.com/v1/image-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hero-2026-10-09-001" \
  -d '{
    "prompt": "Product hero shot of a matte black bottle on marble",
    "webhook_url": "https://hooks.example.com/sume"
  }'
# No "mode" field: because webhook_url is present, the job runs in webhook mode.

What arrives, and what does not

Job webhooks are terminal-only. Exactly three events exist: job.completed, job.failed, and job.canceled. There are no progress or partial callbacks. If you want progress, submit async and read GET /v1/jobs/:id/events, which is a pull snapshot, not a stream.

The delivery is signed with HMAC-SHA256 over {timestamp}.{raw_body}, with x-sume-webhook-timestamp and x-sume-webhook-signature: sume-v1=.... Verify it, store it, answer 2xx, and keep the status_url polls available for deliveries that never arrive. A webhook is a delivery optimization, not your only recovery path.

Practical checks

Log the job id from the 202 response before you do anything else. If your endpoint returns an error, the job is not lost: Sume retries, and you can still poll or redeliver. Use a tunnel with a public HTTPS name during development, since localhost URLs are rejected.

Store the signing secret from GET /v1/webhooks/signing-secret on the server, which needs the account:read scope, and verify every delivery before trusting it.