Skip to content

Jobs and webhooks in the API

Most runs finish after the call that starts them. You get a job back: follow it, wait on it for up to a minute, or name a webhook address and we'll POST the job there once it's done or has failed, signed with your key's secret.

Updated · 2 min read

On this page
  1. 01Three ways to know when it's ready
  2. 02What a webhook sends

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.

An answer that lists work names each piece's job the same way. Your recent work in a studio (GET /work) and a board's cards (GET /boards/{boardId}) give it as job, with the kind, the id and the url to read it. Pass the id to GET /jobs/{id}, or read the url, just as for a job a run gave you. A piece made at once, such as a picture or a voiceover, has job: null.

A UGC ad made with pictureFirst: true, Step by step on the page, stops once its preview is in, with the status waiting. Its files hold the preview and its notes say what the video costs now. Nothing more is made until you call POST /ugc-ads/{adId}/video to make the video, or POST /ugc-ads/{adId}/picture to draw the preview again. Each one has a free quote, and adId is the job's id after ugc..

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. A UGC ad made step by step sends job.waiting once its preview is in, and that ends its webhook: name a webhookUrl again when you make its video. 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.

Was this helpful?

Still stuck?

A person reads every message.

Usually within 4 hours on a working day. support@team.vessero.com