Skip to content
Log in
Developer API
Get your keyGet a key

Get started

Webhooks

Name a webhookUrl on a run, and once its job is done or has failed, we POST the job there, signed with your key’s secret.

What we POST

POST https://example.com/hooks/vessero
webhook-id: evt_Qm3xT8aLp2Vd9WcZ
webhook-timestamp: 1762179667
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "evt_Qm3xT8aLp2Vd9WcZ",
  "type": "job.done",
  "createdAt": "2026-11-03T14:21:07Z",
  "data": {
    "object": "job",
    "id": "video.8f1c2d3e-4b5a-4789-8abc-def012345678",
    "kind": "video",
    "status": "done",
    "stage": "Finished",
    "files": [
      {
        "kind": "video",
        "url": "https://vessero.com/f/Qm3xT8aLp2Vd9WcZ"
      }
    ],
    "url": "/api/v1/jobs/video.8f1c2d3e-4b5a-4789-8abc-def012345678"
  }
}

Check it · Node

import { Webhook } from 'standardwebhooks';

// The key's own secret, from Vessero's Settings → API: whsec_…
const hook = new Webhook(process.env.VESSERO_WEBHOOK_SECRET);

app.post('/hooks/vessero', express.raw({ type: 'application/json' }), (req, res) => {
  const event = hook.verify(req.body, req.headers); // throws on a bad signature
  if (event.type === 'job.done') saveFiles(event.data.files);
  res.sendStatus(204); // within 10 seconds
});

What we send

The body is { "id", "type", "createdAt", "data" }: type is job.done or job.failed, and data is the job, as GET /jobs/{jobId} reads it.

Check the signature

Each delivery is signed the Standard Webhooks way, with three headers: webhook-id, webhook-timestamp and webhook-signature (v1, and the base64 HMAC-SHA256 of id.timestamp.body). The secret is your key’s own, starting whsec_: open the key in Settings → API and press Reveal. Any Standard Webhooks library checks it for you, as in the code beside this.

Answer quickly

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: use webhook-id to tell.

The address

It must be public and https. Addresses on private networks are refused, and redirects are not followed. We watch a job for up to two days. Revoking the key stops its webhooks.