Webhook payload too large (1 MiB)? Fetch the result URL
A Sume run receipt over 1 MiB arrives with payload null and a payload_too_large error. The run did not fail; fetch the receipt from result_url. Handler steps.
When a Sume run receipt is over 1 MiB it cannot be delivered inline: the webhook arrives with payload: null and an error of code payload_too_large that carries a result_url. The run did not fail. Fetch the full receipt from that URL and carry on.
This is documented for run webhooks (Action, Format and Agent Completion runs) in Run webhooks, read 2026-09-29. It is a delivery limit, not a run outcome.
What does an oversized delivery look like?
The envelope is still sent; only the receipt is withheld. status still reports the run's real outcome, so a run that succeeded and was too large to ship arrives with status: OK.
| Field | Normal delivery | Oversized delivery |
|---|---|---|
status | OK or ERROR | Real outcome, for example OK |
payload | The full run receipt | null |
error | null when status is OK | { code: payload_too_large, message, result_url } |
Why is the body limit 1,048,576 bytes?
The error message names the limit: "Run receipt exceeded the 1048576-byte webhook body limit. Fetch the receipt from result_url instead." That is 1 MiB, so it is a size cap on the delivery body. Nothing in the docs says how to shrink a receipt, so plan for the fetch.
How should the handler branch?
Do not treat payload: null as a failure, and do not read status alone as "I have the output". Check error.code first: if it is payload_too_large, fetch error.result_url with your API key and use the response as the receipt. Otherwise use payload, and branch on outcome for usable output.
curl -sS "$RESULT_URL" \
-H "Authorization: Bearer $SUME_API_KEY"What is result_url?
It is the run's result endpoint. For an Action run, GET /v1/action-runs/{run_id}/result returns the full receipt. The docs also say a delivery outcome never changes the run itself, so a run whose webhook could not carry the receipt is still completed, and polling status_url and result_url remains supported as a backup.
What else is in the envelope?
The rest of the envelope is intact. event names the run family, run_id names the run, and request_id equals run_id and stays stable across retries, so dedupe on it. created_at says when that delivery body was built and is the field to use for ordering, since request_id cannot order retries.
Return 2xx quickly after durably recording the event, oversized or not. A slow endpoint burns the 10-second attempt budget and gets retried, and each retry of the same run carries the same request_id.
Does a large receipt count as a failed delivery?
No. The delivery itself succeeded if your endpoint answered 2xx; the receipt was simply too big to ship. Separately, an endpoint that refuses all ten attempts leaves a failed delivery and a run that is still completed, and you fetch it from result_url in that case too. Either way the run and its billing are unaffected by how the webhook went.
Sources
Related posts
More in Developers
- Webhook endpoint redirect 301 not followed: what Sume does
Sume does not follow redirects on webhook deliveries: a 3xx is a failed attempt, not a delivery. Point webhook_url at the final URL, not a hop.
- Webhook dedupe id stable across retries: request_id and created_at
On Sume run webhooks, dedupe on the envelope request_id, which equals run_id and repeats on every retry. Order by created_at; request_id cannot.
- Webhook retry: fixed delay vs exponential backoff, with numbers
Fixed delay retries at even gaps; exponential backoff doubles them. Sume uses fixed for job webhooks and backoff for run webhooks: how long each keeps trying.
- Webhook unknown event type: return 204, not a 500
One Sume verifier covers run and job webhooks. Route on event and answer 204 for unknown types so a new event never becomes a 500 and a retry storm.
Written by Sume