Appearance
Webhooks
Add an endpoint in Webhooks in the dashboard to receive account events as JSON POSTs. The signing secret (whsec_…) is shown once when you add it.
Events
| Type | When | data |
|---|---|---|
balance.low | Balance falls below your alert threshold | balance_usd, threshold_usd |
spend.spike | An hour's spend is over 10× your recent hourly average | hour_spend_usd, average_hour_spend_usd |
credits.purchased | Credits were added | credit_usd, kind (purchase) |
job.completed | A crawl (or other job) finished or was cancelled | job_id, kind, summary |
job.failed | A job failed (e.g. out of credits) | job_id, kind, summary, error |
api_key.leaked | A key was found in public and revoked | key_id, name, display_prefix, url, source |
Every delivery has the same envelope:
json
{
"id": "6f0f…",
"type": "balance.low",
"created": 1763078400,
"org_id": "e23c…",
"data": { "balance_usd": "4.12", "threshold_usd": "5" }
}id is unique per event: use it to ignore duplicates, since delivery is at least once.
Verifying signatures
Each request has a Usefully-Signature: t=<unix seconds>,v1=<hex> header, where v1 = HMAC-SHA256(secret, "<t>.<raw body>"), the scheme many payment providers use. Verify it on the raw body, compare in constant time, and reject old timestamps:
ts
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody: string, header: string, secret: string, toleranceSec = 300): boolean {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2) as [string, string]));
const t = Number(parts.t);
if (!parts.v1 || !Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}python
import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
try:
t = int(parts["t"])
except (KeyError, ValueError):
return False
if abs(time.time() - t) > tolerance or "v1" not in parts:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])Delivery and retries
Respond with any 2xx within 10 seconds. Otherwise the delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then marked failed. Redirects aren't followed. Endpoints must be public https:// URLs; private and internal addresses are refused.