Webhooks

Sume can send a webhook when an avatar or avatar video job reaches a terminal state. Polling remains supported; webhooks are optional and are configured per request with webhook_url.

Configure a webhook

Add webhook_url to POST /v1/avatars or POST /v1/avatar-videos:

Production webhook URLs must use https:// and a public host.

Event types

Event	Sent when
`avatar.ready`	An avatar is ready to use for UGC video generation.
`avatar.failed`	Avatar creation failed. See `data.object.error`.
`avatar_video.ready`	An avatar video finished successfully and `video_url` is available.
`avatar_video.failed`	Avatar video generation failed. See `data.object.error`.

Payload

Webhook payloads use the same public object shape as the matching GET endpoint.

Do not assume the event order across different jobs. Use data.object.id and id for idempotency.

Headers

Each webhook request includes:

Header	Description
`X-Sume-Event-Id`	Stable event ID for this resource and terminal event type.
`X-Sume-Timestamp`	Unix timestamp in seconds.
`X-Sume-Signature`	HMAC SHA-256 signature, formatted as `v1=<hex>`.

Sume signs the string ${timestamp}.${rawBody} using the webhook signing secret provided for your integration.

Verify signatures

Reject events with an old X-Sume-Timestamp to reduce replay risk.

Sume attempts delivery when the job reaches ready or failed. Delivery uses a bounded timeout and a small number of exponential-backoff retries. Webhook delivery failures do not change the job status, credit capture, or credit refund behavior.

Sume may send duplicate events, so store processed X-Sume-Event-Id values on your side and return a 2xx response for duplicates. If all retry attempts fail, polling remains the source of truth for the final job state.