Webhooks

Webhooks push BugBrain events to a URL you control, so your own systems can react the moment a run finishes or a PR check completes. This guide covers subscribing, verifying signatures, and the safety and retry behavior.

What it is#

A webhook is an HTTP endpoint you host. You register its URL and choose which events to subscribe to; when one of those events happens, BugBrain POSTs a signed JSON payload to your URL. The available events are:

• run.completed — a test run finished.
• run.failed — a run couldn't complete.
• pr.check.completed — a PR automation check finished.

Webhooks are org-scoped — they belong to the whole workspace, not a single project.

Why use it#

• Build your own automation — kick off a deploy, update a dashboard, or post to a custom channel when a run completes.
• Real-time, push-based — no polling; BugBrain calls you the instant something happens.
• Verifiable and safe — signed deliveries let you trust the payload, and built-in safety checks protect both sides.

Before you start#

• For an API-key principal, creating a webhook requires the webhooks:write scope — a privilege-sensitive scope that's hard-enforced on the server. See API keys.
• Have an endpoint ready that accepts a POST and responds 2xx quickly.

Create a webhook#

1. 1

   Register the URL

   Add your endpoint's URL and select the events to subscribe to.
2. 2

   Copy the signing secret

   A signing secret that starts with whsec_ is shown once. Copy and store it now — you'll need it to verify deliveries, and you can't view it again.
3. 3

   Confirm deliveries arrive

   Trigger a subscribed event and confirm your endpoint receives the POST.

Verify the signature#

Every delivery is signed with HMAC-SHA256 using your signing secret and carries an X-BugBrain-Signature header in the form t=…, v1=…:

• t is the timestamp the request was signed.
• v1 is the HMAC of the timestamp combined with the request body.

To verify, recompute the HMAC over the timestamp and the raw body using your whsec_… secret, and compare it to v1. Because the signature covers the timestamp, deliveries are replay-protected — reject ones whose timestamp is too old.

Delivery, retries, and safety#

• Retries — a non-2xx response is a failure and is retried with backoff. Respond 2xx as soon as you've accepted the payload, then process it asynchronously.
• SSRF protection — your URL is checked at registration and again at delivery time with DNS resolution, so BugBrain never posts to a private, internal, or metadata address — even if DNS later changes.

Tips#

• Acknowledge fast (return 2xx) and do the real work in the background, so a slow handler doesn't trip the retry logic.
• Always verify the signature before trusting a payload — it's the only way to know a request truly came from BugBrain.
• Use a public HTTPS endpoint; private and internal addresses are rejected by the safety check by design.

Related#