Webhooks

Webhooks & monitoring

Create a monitor to re-scan any URL on a schedule and receive an HMAC-signed webhook whenever its agent-readiness score changes.

How it works

Register a monitor with a target URL and a webhook callback_url. BotVisibility re-scans the target on your chosen cadence and delivers a signed event when the readiness score or level changes — ideal for watching your own site, or a dependency, for regressions.

Two event types: score.changed (fires only when the score or level moves) and scan.completed (fires after every scheduled scan).

Create a monitor

curl -X POST https://botvisibility.com/api/monitors \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "callback_url": "https://hooks.example.com/botvisibility", "events": ["score.changed"], "interval_sec": 86400 }' # -> { "id": "mon_…", "secret": "whsec_…", ... } (secret shown once)

Manage a monitor with GET / DELETE /api/monitors/{id}, and fire a sample delivery with POST /api/monitors/{id}/test.

Verifying signatures

Every delivery includes an X-BotVisibility-Signature header. Recompute the HMAC with your monitor secret and compare in constant time; reject timestamps outside a ~5-minute window.

X-BotVisibility-Signature: t=<unix>,v1=<hex hmac_sha256(t + "." + body)> expected = hmac_sha256(secret, f"{t}.{raw_body}").hexdigest() assert constant_time_eq(expected, v1) and abs(now - t) < 300

Full payload schema is in openapi.json (see x-webhooks), with the auth walkthrough at auth.md and API reference in the developer docs.