Webhook or polling for Sume Format runs, and the 1 MiB payload rule
Pick between the signed terminal webhook and polling status_url for Sume Format runs: delivery limits, dedupe keys, and what a payload over 1 MiB looks like.
Use the webhook when your service is reachable and you want one push per run; poll status_url when it is not, or as a safety net. Each run sends one signed POST of type format.run.terminal, with status OK or ERROR and outcome ok, degraded or error. Cancel and skipped runs do not deliver.
A receipt over 1 MiB is sent as payload: null with payload_too_large and a result_url, so your handler must be able to fetch.
Webhook versus poll
| Aspect | Webhook | Poll status_url |
|---|---|---|
| Direction | Sume calls you | You call Sume |
| Retries | Up to 10 attempts | Yours |
| Cancel and skipped | Never delivered | Visible as terminal status |
| Large result | payload null, use result_url | Read result_url |
| Dedupe | request_id or run_id | Not needed |
Run both
Webhook as the fast path, one poll at expires_at as the backstop. Both paths are idempotent reads of the same terminal state, so handling the first one and ignoring the second is safe.
Sources
Related posts
More in Formats
- Format structured output: anyOf passes, oneOf and allOf are rejected
Which JSON Schema keywords a Sume Format output_schema accepts, the 400 output_schema_invalid shape, and how it lines up with OpenAI strict structured outputs.
- Format output filled_by: agent versus projection, exact URLs
Sume Format runs fill structured output either through the agent or by projection. Learn which one ran, what projection can see, and the exact-URL gate.
- Sume SDK subscribeFormatRun: 20-minute timeout vs 90-minute runs
subscribeFormatRun in @sume-com/sdk polls every 2 seconds and times out at 20 minutes by default, while a Format run can live 90. Set the timeout on purpose.
- Shop Creative Hub limits: 50 per upload, 10k a month, batch math
Creative Hub for GMV Max takes 50 videos per upload and 10k a month. What that means for Sume bulk queues of 100, and where the 200-video link cap bites.
Written by Sume