Webhooks

For event-driven integrations — Slack notifications, downstream pipelines, status dashboards — webhooks are the right tool.

Configuring a webhook

In Settings → Webhooks:

URL — your endpoint
Events — which events fire (build complete, build failed, etc.)
Active — enable / disable without deleting

You can register multiple webhooks per org. Each fires independently.

What gets sent

Webhooks POST a JSON envelope to your URL:

{
  "type": "build.complete",
  "createdAt": "...",
  "organizationId": "...",
  "data": {
    "build": {
      "id": "...",
      "status": "complete",
      "platform": "Win64",
      "buildType": "Development",
      "branch": "main",
      "commit": "...",
      "durationMs": 763000,
      "artifactUrl": "https://..."
    },
    "project": { "id": "...", "name": "MyGame" }
  }
}

The type field tells you which event fired. Common ones:

Event	When
`build.created`	A new build is dispatched
`build.running`	The build picks up and starts running
`build.complete`	Build succeeded; artifact is available
`build.failed`	Build failed
`build.superseded`	Replaced by a newer build

Verifying signatures

The request includes an X-BuildPixel-Signature header — an HMAC of the body using your webhook signing secret. Verify before trusting:

import crypto from "node:crypto";

function verifySignature(req, secret) {
  const sig = req.headers["x-buildpixel-signature"];
  if (!sig?.startsWith("sha256=")) return false;
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(req.rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

The signing secret is generated when you create the webhook and shown in the Settings UI.

Retries

If your endpoint returns non-2xx, BuildPixel retries with exponential backoff for a few attempts before giving up. Failed deliveries are visible in the dashboard’s webhook delivery log.

Common patterns

app.post("/webhooks/buildpixel", async (req, res) => {
  if (!verifySignature(req, SECRET)) return res.sendStatus(401);
  const event = JSON.parse(req.body);

  if (event.type === "build.complete") {
    const { build, project } = event.data;
    await fetch(SLACK_WEBHOOK_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        text: `:rocket: ${project.name} ${build.platform} ${build.buildType} build complete`,
      }),
    });
  }
  res.sendStatus(204);
});

if (event.type === "build.complete" && event.data.build.buildType === "Shipping") {
  await fetch(DOWNSTREAM_URL, {
    method: "POST",
    body: JSON.stringify({ buildId: event.data.build.id })
  });
}

Overview

Endpoints

Real-time

Webhooks

Configuring a webhook

What gets sent

Verifying signatures

Retries

Common patterns

​Configuring a webhook

​What gets sent

​Verifying signatures

​Retries

​Common patterns

Configuring a webhook

What gets sent

Verifying signatures

Retries

Common patterns