Webhooks
Use webhooks when your server should be notified when a job reaches a terminal state.
Submit with a webhook URL
Send mode: "webhook" with webhook_url.
Webhook URLs must be public HTTPS URLs. Localhost, private-network, and non-HTTPS URLs are rejected.
Events
Sume sends terminal job events:
| 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 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:
Reject callbacks when the timestamp is outside your replay tolerance window. Five minutes is a reasonable default.
Verify in TypeScript
Delivery behavior
Return any 2xx response after durably storing the event. Network errors and
non-2xx responses are retried with bounded backoff until attempts are exhausted.
Use job_id as the idempotency key on your side.
Webhook delivery status is visible on the job object and in job events when available.