Sume video callback_url must be HTTPS: a webhook instead of polling
POST /v1/videos accepts callback_url, which must be HTTPS. Event names, the signature header, retries, and when a poll loop is still the safer choice.
Add callback_url to a Sume video request if you want a push instead of a poll. The URL must be HTTPS. Sume's webhook docs list job.completed, job.failed and job.canceled events, signed with a header in the form sume-v1=<hex> computed over the timestamp, a dot and the raw body. Failed deliveries are retried up to 10 times, 30 seconds apart.
What your receiver must do
Requests carry x-sume-webhook-signature and x-sume-webhook-timestamp headers.
- Read the raw body before any JSON parsing; the signature covers the raw bytes.
- Refuse to verify when your signing secret is empty.
- Reply 2xx quickly and do the work after.
- Treat events as at-least-once and dedupe by job id.
Webhook or poll
Job statuses are pending, in_progress, completed, failed and cancelled; a poll loop should stop on any of the last three.
| Situation | Better choice |
|---|---|
| Public HTTPS endpoint you control | callback_url |
| Script on a laptop or behind a firewall | Poll GET /v1/videos/{id} |
| Cannot afford a missed event | Both: webhook plus a sweeper that polls stuck jobs |
Sources
Related posts
More in Developers
- Sume video job failed: retry, new key, or switch the model?
A failed video job is final, and an Idempotency-Key replay returns the same failed job. Read the error, then retry with a new key or change models.
- Sume video pricing fields: list_basis and billable_margin
How to read the pricing object on a Sume video model: per second, by resolution, or per 1,000 video tokens, and why to read billable_margin, not hard-code 1.25.
- Sume video submit 415: send JSON and pass images as URLs
POST /v1/videos answers 415 unsupported_media_type when the body is not application/json. How to read details.received_content_type and send frames as URLs.
- Sume video sync submit: timed_out and capacity_exhausted flags
A sync submit returns 2xx with a job id even when the wait runs out. What the sync object says and what to do next.
Written by Sume