Jobs and webhooks in the API

A picture or a voiceover comes back in the call itself, with what it made. A run that takes a while answers with a job as soon as it starts, and so does a picture still being made after about 45 seconds, from a slow model or a busy queue. The job has an id, a status (working, done or failed) and a stage that says in words what is happening, such as "Rendering". There is no time estimate. Once it's done, files holds links to what it made. The links last about 7 days, and reading the job again gives fresh ones. Everything a job makes is also kept in your Library.

Three ways to know when it's ready

• Read it again. GET /jobs/{id} answers the job as it is now. Every few seconds is fine.
• Wait on the call. Send Prefer: wait=30 with the run, and the answer waits up to that many seconds, at most 60, for the job to end. No call runs past 80 seconds in all, so a picture that already waited gets less. That suits quick runs.
• Name a webhook. Put webhookUrl in the run's body: an https address on your server. Once the job is done or has failed, we POST it there.

What a webhook sends

The body is { "id", "type", "createdAt", "data" }, where type is job.done or job.failed and data is the job. Each one is signed the Standard Webhooks way, with three headers: webhook-id, webhook-timestamp and webhook-signature. Check the signature with your key's signing secret, which starts whsec_ and is shown under the key in Settings → API. Any Standard Webhooks library checks it for you.

Answer with a 2xx within 10 seconds. If your address doesn't answer, or answers with anything else, we try again with a growing wait for about two hours. The same event can arrive twice, so use webhook-id to tell. We watch a job for up to two days.

A webhook address must be public and https. Addresses on private networks are refused, and we don't follow redirects. Revoking the key stops its webhooks.