Webhook events

BugBrain can POST a signed JSON payload to your endpoint when key events happen. This page lists the event types, the payload shape, and how to verify a delivery. To register and manage webhooks, see Webhooks.

Event types#

Event	Fires when
run.completed	A test run finished. The payload carries the run's result data.
run.failed	A test run could not complete (e.g. the site was unreachable or login failed).
pr.check.completed	A PR-automation check finished. The payload carries the pull request, repo, conclusion, impacted areas, and an issue summary.

A webhook subscribes to one or more of these events; only subscribed events are delivered.

Payload shape#

Each delivery is a JSON body containing the event type plus the relevant data for that event (the run for run events, or the PR check details for pr.check.completed). A typical run-event body looks like:

{
  "event": "run.completed",
  "data": {
    "runId": "…",
    "projectId": "…",
    "status": "COMPLETED",
    "issuesFound": 3
  }
}

Verifying the signature#

Every delivery includes the header:

X-BugBrain-Signature: t=<timestamp>, v1=<hmac>

• t is the Unix timestamp (in seconds) that was signed.
• v1 is HMAC-SHA256(secret, "<t>.<rawBody>"), hex-encoded.

To verify, recompute the HMAC over "<t>.<rawBody>" with your signing secret and compare it to v1 using a constant-time comparison. The signed timestamp gives replay protection: reject the request if t is outside your tolerance window (a few minutes is typical).

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = header.split(",").map((p) => p.trim());
  const t = Number(parts.find((p) => p.startsWith("t="))?.slice(2));
  const sig = parts.find((p) => p.startsWith("v1="))?.slice(3);
  if (!Number.isFinite(t) || !sig) return false;
  // Replay protection: reject stale timestamps.
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(sig, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

The signing secret#

When you create a webhook, BugBrain returns a signing secret that starts with whsec_. It is shown once and never retrievable again — store it securely at creation time. If you lose it, rotate the webhook to get a new one.

Delivery and retries#

• Your endpoint should respond with a 2xx status quickly; do slow work asynchronously.
• A non-2xx response is retried with exponential backoff.
• A destination that is disabled or fails a safety check (an unsafe or private URL) is not retried.

Related#