Webhooks

Rendobar can send HTTP POST requests to your server when job status changes. Webhooks provide a push-based alternative to polling the jobs endpoint, allowing your application to react to completed, failed, or cancelled jobs in real time.

Webhooks are available on Starter plans and above.

Setting up webhooks

Configure a webhook URL for your organization by updating your org settings via the API:

curl -X PATCH https://api.rendobar.com/orgs/YOUR_ORG_ID \
  -H "Authorization: Bearer rb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhooks/rendobar",
    "webhookSecret": "your-secret-string"
  }'

The webhookSecret is used to generate HMAC signatures so you can verify that incoming requests actually came from Rendobar.

Event types

Rendobar sends webhooks for the following events:

Webhook payload

Every webhook delivery sends a JSON payload with this structure:

{
  "event": "job.completed",
  "jobId": "job_a1b2c3d4",
  "result": {
    "url": "https://r2.rendobar.com/...",
    "metadata": {
      "durationMs": 127500,
      "width": 1920,
      "height": 1080,
      "fileSize": 15234567
    }
  },
  "cost": {
    "credits": 3,
    "breakdown": "2m7s video"
  },
  "timing": {
    "createdAt": 1707436800000,
    "startedAt": 1707436805000,
    "completedAt": 1707436815000
  }
}

For job.failed events, the payload includes error instead of result:

{
  "event": "job.failed",
  "jobId": "job_a1b2c3d4",
  "error": {
    "code": "PROVIDER_ERROR",
    "message": "FFmpeg process exited with code 1"
  },
  "timing": {
    "createdAt": 1707436800000,
    "startedAt": 1707436805000,
    "completedAt": 1707436810000
  }
}

HMAC signature verification

Every webhook request includes a signature header for verification:

X-Rendobar-Signature: sha256=abc123def456...
X-Rendobar-Event: job.completed
X-Rendobar-Delivery: del_x1y2z3
X-Rendobar-Attempt: 1

To verify the signature, compute an HMAC-SHA256 digest of the raw request body using your webhook secret, then compare it with the value in the X-Rendobar-Signature header.

Verification example (Node.js)

import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(body, signature, secret) {
  const expected = createHmac("sha256", secret)
    .update(body, "utf8")
    .digest("hex");

  const received = signature.replace("sha256=", "");

  return timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

// In your webhook handler:
app.post("/webhooks/rendobar", (req, res) => {
  const signature = req.headers["x-rendobar-signature"];
  const rawBody = req.rawBody; // raw string, not parsed JSON

  if (!verifySignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.body;
  // Process the event...
  res.status(200).send("OK");
});

Always use a timing-safe comparison function to prevent timing attacks.

Retry policy

If your endpoint does not return a 2xx status code within 10 seconds, Rendobar retries the delivery:

After 3 failed attempts, the delivery is marked as failed. You can check delivery status via the API:

curl https://api.rendobar.com/jobs/job_a1b2c3d4 \
  -H "Authorization: Bearer rb_live_YOUR_KEY"

The job record includes webhook delivery metadata in the response.

Best practices

• Return 200 quickly. Process the webhook payload asynchronously. If your handler takes too long, Rendobar may time out and retry, leading to duplicate deliveries.
• Handle duplicates. Use the X-Rendobar-Delivery header or jobId to deduplicate. The same event may be delivered more than once due to retries.
• Verify signatures. Always validate the HMAC signature before processing any webhook payload.
• Use HTTPS. Webhook URLs must use HTTPS in production to protect the payload in transit.

Next steps

• Quickstart to submit your first job
• Job Types for all available operations
• Credits for billing details
• MCP Integration for AI agent access