Webhooks for job events

Rendobar POSTs JSON to your endpoint when a job changes status.

Set up a webhook

curl -X POST https://api.rendobar.com/webhooks/endpoints \
  -H "Authorization: Bearer rb_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://your-server.com/webhooks/rendobar",
    "subscribedEvents": ["job.completed", "job.failed"]
  }'

Required: name (1–50 chars), url (must be HTTPS), subscribedEvents (≥ 1). The response includes a signing secret (whsec_...). Store it. You’ll verify every payload against it. Manage endpoints (create, update, delete, test) via the API or the dashboard.

Events

Subscribe to any of these when you create an endpoint.

Event	When
`job.created`	Job accepted and queued
`job.started`	Job started executing on a runner
`job.completed`	Job finished successfully. Carries the unified `output` and `cost`
`job.failed`	Job failed. Carries the unified `error` (`code`, `message`, `detail`, `retryable`)
`job.cancelled`	Job was cancelled
`balance.low`	Credit balance crossed the low threshold
`balance.depleted`	Credit balance reached zero

Payload

X-Rendobar-Signature: sha256=abc123...
X-Rendobar-Timestamp: 1707436815
X-Rendobar-Event: job.completed
X-Rendobar-Delivery: del_x1y2z3
X-Rendobar-Attempt: 1

Every delivery is a versioned envelope. The envelope fields identify the event and delivery. The event-specific payload lives under data. For job events, data carries the same contract as GET /jobs/.

Envelope field	Meaning
`version`	Envelope schema version (currently `"1"`)
`event`	The event name (see the table above)
`deliveryId`	Unique per delivery. Use it to deduplicate
`timestamp`	When the envelope was built (unix ms)
`orgId`	Your organization ID
`data`	Event-specific payload

A job.completed delivery. data.output is the unified job output. file.url is a signed, time-limited URL, and files lists every produced file. Read Job output for the full shape and the four output patterns.

{
  "version": "1",
  "event": "job.completed",
  "deliveryId": "whd_x1y2z3",
  "timestamp": 1707436815000,
  "orgId": "org_abc123",
  "data": {
    "jobId": "job_a1b2c3d4",
    "jobType": "ffmpeg",
    "status": "complete",
    "output": {
      "data": null,
      "file": {
        "url": "https://api.rendobar.com/dl/job_a1b2c3d4?token=...",
        "path": "output.mp4",
        "type": "video",
        "size": 15234567,
        "meta": { "format": "mp4", "width": 1920, "height": 1080, "durationMs": 127500 }
      },
      "files": [
        {
          "url": "https://api.rendobar.com/dl/job_a1b2c3d4?token=...",
          "path": "output.mp4",
          "type": "video",
          "size": 15234567,
          "meta": { "format": "mp4", "width": 1920, "height": 1080, "durationMs": 127500 }
        }
      ],
      "expiresAt": 1707440415000
    },
    "cost": { "amount": 50000000, "currency": "USD", "formatted": "$0.05" },
    "timing": {
      "createdAt": 1707436800000,
      "startedAt": 1707436805000,
      "completedAt": 1707436815000
    }
  }
}

The output shape is identical for every job type. A data-only job (such as extract.metadata) carries its answer in output.data with file null and files empty. A stream job carries the manifest as output.file and every segment in output.files. See Job output for each pattern. For job.failed, data carries error instead of output. The error matches the GET /jobs error shape: code, message, detail (the process stderr tail, or null), and retryable.

{
  "version": "1",
  "event": "job.failed",
  "deliveryId": "whd_a4b5c6",
  "timestamp": 1707436810000,
  "orgId": "org_abc123",
  "data": {
    "jobId": "job_a1b2c3d4",
    "jobType": "ffmpeg",
    "status": "failed",
    "error": {
      "code": "RUNNER_ERROR",
      "message": "FFmpeg process exited with code 1",
      "detail": "Conversion failed: Invalid data found when processing input",
      "retryable": false
    },
    "timing": { "createdAt": 1707436800000, "startedAt": 1707436805000, "failedAt": 1707436810000 }
  }
}

Verify the signature

The signature is HMAC-SHA256 over {timestamp}.{body} using your webhook secret. Timestamp-prefixed to prevent replays.

import { verifyWebhook } from "@rendobar/sdk/webhooks";

// Pass the raw body (not parsed JSON) and the request headers. verifyWebhook
// reads the signature and timestamp, rebuilds the signed string, checks the
// timestamp is recent (replay protection), and handles secret rotation.
const ok = await verifyWebhook(rawBody, req.headers, process.env.WEBHOOK_SECRET);
if (!ok) throw new Error("Invalid signature");

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhook(body, signature, timestamp, secret) {
  const message = `${timestamp}.${body}`;
  const expected = createHmac("sha256", secret).update(message, "utf8").digest("hex");
  const received = signature.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(received, "hex"));
}

app.post("/webhooks/rendobar", (req, res) => {
  const ok = verifyWebhook(
    req.rawBody,                           // raw string, not parsed JSON
    req.headers["x-rendobar-signature"],
    req.headers["x-rendobar-timestamp"],
    process.env.WEBHOOK_SECRET
  );
  if (!ok) return res.status(401).send("Invalid signature");
  // process req.body...
  res.status(200).send("OK");
});

import hmac, hashlib

def verify_webhook(body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    message = f"{timestamp}.{body.decode()}"
    expected = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()
    received = signature.replace("sha256=", "")
    return hmac.compare_digest(expected, received)

Always use a timing-safe comparison (timingSafeEqual / hmac.compare_digest). String equality leaks signature bytes through timing.

Secret rotation

Rotation has a 24-hour window. During it, Rendobar sends both X-Rendobar-Signature (new secret) and X-Rendobar-Signature-Previous (old). Verify against either.

SSRF protection

URLs must be HTTPS. Delivery to private/reserved ranges (10.x, 172.16-31.x, 192.168.x, 127.x, ::1) is blocked.

Retries

If your endpoint doesn’t return 2xx within 10 seconds, Rendobar retries up to 5 times with exponential backoff. The delay doubles each attempt and caps at 5 minutes.

Retry	Delay before it
1st	10 s
2nd	20 s
3rd	40 s
4th	80 s
5th	160 s

After the retries are exhausted the delivery is marked failed. A delivery whose status is failed or cancelled can be re-sent from the dashboard or the API. Inspect history:

curl "https://api.rendobar.com/webhooks/deliveries?endpointId=YOUR_ENDPOINT_ID" \
  -H "Authorization: Bearer rb_YOUR_KEY"

An endpoint that fails 10 deliveries in a row is disabled automatically. Update or re-enable it to reset the counter.

Best practices

Return 200 fast. Process asynchronously. Long handlers trigger retries → duplicate deliveries.
Deduplicate on X-Rendobar-Delivery or jobId. Same event can arrive more than once.
Verify every signature before reading the body.

Getting Started

Concepts

Jobs

Integrations

Support

Webhooks for job events

Set up a webhook

Events

Payload

Verify the signature

Secret rotation

SSRF protection

Retries

Best practices

See also

​Set up a webhook

​Events

​Payload

​Verify the signature

​Secret rotation

​SSRF protection

​Retries

​Best practices

​See also

​Related

Set up a webhook

Events

Payload

Verify the signature

Secret rotation

SSRF protection

Retries

Best practices

See also

Related