Skip to main content
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:
EventWhen
build.createdA new build is dispatched
build.runningThe build picks up and starts running
build.completeBuild succeeded; artifact is available
build.failedBuild failed
build.supersededReplaced 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);
});