Webhooks

Use webhooks if your server needs a notification when a job reaches a terminal state.

This page is about generation jobs. Sume has two webhook surfaces:

You called	You get	Documented at
POST /v1/models/... or a model endpoint like /v1/avatar-1.0/generate	job.completed / job.failed / job.canceled	This page
An Action, Format, or Agent Completion run endpoint	action.run.terminal / format.run.terminal / agent.run.terminal	Run webhooks

The event sets do not overlap, and the payloads are different. A run webhook carries the full run receipt, not a job result. The signature scheme is identical. Thus, one verifier covers both.

Submit with a webhook URL

Send mode: "webhook" with webhook_url.

Webhook URLs must be public HTTPS URLs. The API rejects localhost, private-network, and non-HTTPS URLs.

Webhook is one of four communication modes. Communication modes compares it to async, sync, and subscribe. That page also describes the poll fallback to keep in place with it.

Events

Sume sends terminal job events only. There are no progress or partial deliveries:

Event	When it is sent
job.completed	The job completed and a public result is available.
job.failed	The job failed with a public error.
job.canceled	The job reached the canceled state.

Payload

Failed and canceled webhooks use status: "ERROR" and include an error object.

Signature headers

When webhook signing is configured, Sume signs the raw JSON body with HMAC SHA 256 over:

Headers:

During a signing-secret rotation, the signature header carries one entry for each live secret. The newest entry is first, and commas separate the entries (sume-v1=<new>,sume-v1=<previous>). Accept the delivery when any sume-v1= entry matches.

Reject callbacks when the timestamp is outside your replay tolerance window. Five minutes is a reasonable default.

Read your signing secret on the Webhooks tab of the dashboard (/dashboard/webhooks — Reveal, then copy). You can also read it from GET /v1/webhooks/signing-secret with an API key that has account:read. Sume derives the secret for your workspace. Thus, it is your secret, not a shared platform value.

Store it as SUME_COM_WEBHOOK_SIGNING_SECRET, the same name that the delivery worker uses. Job webhooks and run webhooks share that one secret. Thus, a single verifier covers both.

Each delivery also carries x-sume-webhook-secret-fingerprint. webhook_delivery.signing_secret_fingerprint on the receipt gives the same value. If a signature does not verify, compare that fingerprint with the fingerprint next to the secret in the dashboard. Neither side ever needs to send the secret itself.

Verify in TypeScript

Delivery behavior

After you store the event durably, return any 2xx response. Sume retries network errors and non-2xx responses until it uses all attempts. Use job_id as the idempotency key on your side.

Retries	Up to 10 attempts total.
Spacing	A fixed delay between attempts (30s by default), not exponential backoff.
Timeout	10s for each attempt. A slow endpoint uses the budget, and Sume retries it.

After ten refused attempts, you have a failed delivery and a job that still reached its real terminal state. Delivery is an optimization, never the only recovery path. Keep the status_url polls available for the events that never arrive.

Send test and Redeliver

These are two different actions. Do not use one in place of the other.

Send test is one control on /dashboard/webhooks (or POST /v1/webhooks/test-deliveries with account:write). It POSTs a dummy signed webhook.test payload to a URL that you type. It never replays a real job. The dummy body has no job_id / arun_, and Sume does not append it to Requests.

Redeliver is per call. Use it on each delivery row, or use POST /v1/jobs/{job_id}/webhook/redeliver (jobs:write). Sume then re-POSTs the real terminal event of that job (job.completed / job.failed / job.canceled) with a fresh timestamp and signature. This still works after Sume used all automatic attempts. It does not use one of the automatic 10.

Receivers must treat job_id as the idempotency key. Redeliver does not change the destination URL. A new URL is a new job.

Run webhooks documents Format run redeliver.

Run webhooks use the same 10-attempt cap on a different schedule. That page is the authority for *.run.terminal deliveries.

When it is available, the webhook delivery status, with the attempt count, shows on the job object and in job events.

Next

• Run webhooks — the same signature scheme for Action, Format, and Agent Completion runs