Webhooks

Register an endpoint under Settings → Webhooks, or set callback on an individual render. Both deliver the same payload with the same signature scheme.

An endpoint is a description of the whole request, not just a URL: the method, how the body is encoded, the headers to send, and the payload itself. That is there so you can point us straight at a receiver you do not control — an automation platform, a CRM's inbound hook, a chat webhook — instead of running a service whose only job is renaming our fields.

The secret is shown once at creation. Store it alongside your API key — you need it to verify every delivery.

Subscribe only to what you use. The default — render.completed and render.failed — is what most integrations need.

A render has three endings, not two. If your integration blocks until a render settles, subscribe to render.cancelled as well or a cancelled job will never arrive and the work waiting on it will hang. Treat it as terminal-but-fine: the credits are already back, and unlike render.failed there is nothing to retry.

Four settings decide what arrives at your endpoint. All of them are on the endpoint form, and all of them are accepted by POST /organization/webhooks if you would rather script it.

Under form and multipart, top-level keys of the payload become fields and nested values are sent as JSON text — neither encoding has a notion of nesting.

The URL, every header value and the payload accept {{placeholders}}, resolved against the event as it is delivered. A path that does not exist on a given event never fails the delivery: it resolves to an empty string, or to null where the placeholder is a whole JSON value.

A custom payload is parsed as JSON before substitution and re-serialised after, so a value containing a quote or a newline cannot break the body. It also means a value that is only a placeholder keeps its type: "{{data}}" sends the object, not a string of it.

{
  "event": "{{event.type}}",
  "renderId": "{{data.id}}",
  "status": "{{data.status}}",
  "fileUrl": "{{data.url}}",
  "creditsUsed": "{{data.credits}}",
  "raw": "{{data}}"
}

Left on its default, the body is our event envelope: an event id to deduplicate on, the event type, when it happened, and the event itself under data.

{
  "id": "evt_m1x8k2p9",
  "type": "render.completed",
  "created": "2026-08-13T09:15:48.221Z",
  "data": {
    "id": "rnd_8f2a1c",
    "status": "done",
    "kind": "video",
    "templateId": "story-reel",
    "url": "https://cdn.pixbix.app/render/…/render.mp4",
    "posterUrl": "https://cdn.pixbix.app/render/…/poster.jpg",
    "thumbnailUrl": "https://cdn.pixbix.app/render/…/thumbnail.jpg",
    "format": "mp4",
    "width": 1080,
    "height": 1920,
    "duration": 15.02,
    "fileSizeBytes": 2841022,
    "renderTime": 42180,
    "credits": 15,
    "watermarked": false
  }
}

Every request carries:

X-Pixbix-Event: render.completed
X-Pixbix-Timestamp: 1786000548
X-Pixbix-Signature: sha256=9f2c8a…
X-Pixbix-Attempt: 1
User-Agent: pixbix-webhooks/1.0

The signature is HMAC-SHA256(secret, "{timestamp}.{rawBody}"). Two things matter and both are easy to get wrong:

1. Use the raw body. Re-serialising a parsed JSON body changes key order and whitespace, and the signature will never match. This holds for a custom payload and for the form encodings too: what we sign is the exact bytes we send, whatever shape you configured.
2. Check the timestamp. Rejecting anything older than five minutes is what stops a captured payload being replayed at you later.

import crypto from "crypto";

// express.raw, NOT express.json — we need the exact bytes.
app.post(
  "/hooks/pixbix",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const timestamp = req.get("X-Pixbix-Timestamp") || "";
    const signature = req.get("X-Pixbix-Signature") || "";

    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
      return res.status(400).send("stale");
    }

    const expected = "sha256=" + crypto
      .createHmac("sha256", process.env.PIXBIX_WEBHOOK_SECRET)
      .update(timestamp + "." + req.body.toString())
      .digest("hex");

    const a = Buffer.from(expected);
    const b = Buffer.from(signature);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).send("bad signature");
    }

    const event = JSON.parse(req.body.toString());

    // Acknowledge immediately, then work asynchronously.
    res.sendStatus(200);
    void handleEvent(event);
  },
);

Return 2xx within 10 seconds. Anything else is treated as a failure and retried with exponential backoff — 1s, 4s, 9s, 16s — up to 5 attempts.

• A 4xx other than 429 is not retried: the receiver understood and rejected it, so retrying cannot help.
• An endpoint failing 20 times consecutively is disabled automatically and flagged in the dashboard.
• Re-enabling an endpoint clears its failure streak.

Use a tunnel to reach your machine, register the tunnel URL, and press Send test on the endpoint. The test is built and signed through the same path as a real delivery, so it exercises the method, encoding, headers and payload you configured — and it carries X-Pixbix-Test: true so your handler can tell.

A failed test does not count towards the failure streak that disables an endpoint, so you can iterate on a receiver without being locked out of your own webhook.

# Any tunnelling tool works
ngrok http 3000
# → https://a1b2c3.ngrok.io

# Register https://a1b2c3.ngrok.io/hooks/pixbix in
# Settings → Webhooks, then hit "Send test".

Webhooks are best-effort. A render is still authoritative in the API, so a robust integration reconciles: for any render still marked pending after a reasonable window, call GET /v1/render/{id} and settle from the response.

A sweep every few minutes over renders older than five minutes and not yet terminal is enough, and it makes your pipeline immune to a lost delivery.