Webhooks

Instead of waiting or polling, have Raccord call your server when a check finishes.

curl https://api.kolamlabs.ai/v1/webhooks -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"url": "https://example.com/raccord"}'

The response includes a secret (whsec_…), shown once. Endpoints belong to the key's mode: test keys get events for test checks.

Events

Event	When	`data`
`check.completed`	A check finished	The check object
`check.failed`	A check couldn't run (e.g. an unreadable file); you weren't charged	The check object, with `error`
`credits.added`	A purchase completed	`{"pack", "usd"}`

{"id": "evt_…", "type": "check.completed", "created_at": "2026-11-05T10:00:00Z", "data": {"id": "chk_…", "verdict": "fail", …}}

Verify every delivery

Each delivery has the header Raccord-Signature: t=<unix time>,v1=<hex>.

t is whole seconds.
v1 is the lowercase hex HMAC-SHA256 of the bytes "<t>." + raw body.
The key is your endpoint secret as UTF-8 bytes, including the whsec_ prefix.
There is one v1 per header.

Check it before trusting the body, and reject deliveries more than five minutes old, or more than five minutes in the future.

from raccord_sdk import verify_webhook

if not verify_webhook(secret, request.body, request.headers["Raccord-Signature"]):
    return 400

In any language: compute HMAC_SHA256(secret, t + "." + body) as hex and compare it with v1 in constant time.

Delivery

Answer with a 2xx within 10 seconds. Anything else is retried after 10 s, 1 min, 5 min, 30 min, 2 h, 6 h and 12 h, then dropped.
Deliveries can arrive more than once or out of order. Use the check id to de-duplicate.
URLs must be public https:// addresses.