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.
- SumeMediaFile duration_ms is checked within 10% of the real file
A duration_ms in Format output must match the run's artifact ledger within 10%, or the projection fails. A null means not measured, not zero.
- 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.
Written by Sume