Guides

Webhooks

Webhooks are the preferred way to observe runs. Register an endpoint once and BrowserPilot pushes a signed event for every state change.

Register an endpoint

Add an endpoint URL in Settings → Webhooks. Each endpoint gets its own signing secret. You can register multiple endpoints — every run event fans out to all of them, each with an independent retry schedule and delivery log.

Events

BrowserPilot emits an event for each terminal and progress transition of a run:

run.started     run.step
run.completed   run.failed     run.cancelled

Payload

Every delivery is a JSON POST. The body carries the event name, run id, and run summary:

{
  "event": "run.completed",
  "run_id": "run_9fA2c1",
  "steps": 14,
  "cost_usd": 0.27,
  "output": { "roles": [ ... ] }
}

Verify the signature

Each request carries an x-browserpilot-signature header. Compute the HMAC-SHA256 of the raw body with your endpoint secret and compare it in constant time before trusting the payload.

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Retries

If your endpoint does not return a 2xx, BrowserPilot retries with exponential backoff until it succeeds or the retry window is exhausted. Make your handler idempotent — key on run_id plus event — so a duplicate delivery is harmless.