OpenAI Agents API webhooks: when the agent finishes, and Sume's

OpenAI's Agents API guide says to stream output or use webhooks to learn when the agent finishes or needs input. Sume's Agent Completions have a narrower webhook: one signed agent.run.terminal POST when a run completes or fails, and nothing when it is canceled or when it is only waiting on something.

What does OpenAI say about knowing when an agent is done?

The overview names two ways: stream the output, or use webhooks. It groups two moments together, the agent finishing and the agent needing input. The details of each event are on OpenAI's page and are not covered here.

Which events does a Sume Agent Completion send?

Send communication.webhook_url when you create the completion. Sume's docs list one terminal event per run family, and the outcome lives in status and payload.status, not the event name.

Is there a needs-input event on Sume?

Not in the docs. A run is one agent turn, and its terminal event fires exactly once, however many files that turn produced. Sume's Agent Completions have no interactive approval step at all: the docs say the spend-approval prompt from the chat UI is not available to a backend caller, and that generation_spend_cap_usd is the substitute.

Streaming is also listed under not available yet, so polling status_url or the webhook are the two ways to hear back.

What never arrives?

A canceled run does not deliver a webhook. After POST .../cancel, the docs say to trust the cancel response and poll status_url until payload.status is canceled. A failed run does arrive, with status: "ERROR" and a populated error.

Delivery is up to 10 attempts, with a 10 second timeout per attempt. Dedupe on request_id, which is stable across retries.

How do I verify the delivery?

Sume signs the raw body with HMAC-SHA256 over <timestamp>.<raw_body> and sends x-sume-webhook-signature. The details and a verifier are in Run webhooks.

What should the receiver return?

Return a 2xx quickly, after durably recording the event, and do the processing afterward. Sume's docs say a slow endpoint burns the 10-second attempt budget and gets retried, and that any 2xx counts as success. A 3xx is a failed attempt, because redirects are not followed.

Branch on outcome, not only status: ok, degraded or error. A run can complete and bill you while failing to fill your output_schema, and that arrives as status: "OK" with outcome: "degraded".

What if I want progress inside a turn?

Sume's docs say there is no per-artifact run event and none is planned. Progress inside a turn is the generation-job layer, whose webhooks fire per job as each one completes and name a job, not a step of your recipe. That is a separate surface with its own event set, and the same signature scheme, so one verifier covers both.