Skip to content

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 ​

TypeWhendata
balance.lowBalance falls below your alert thresholdbalance_usd, threshold_usd
spend.spikeAn hour's spend is over 10× your recent hourly averagehour_spend_usd, average_hour_spend_usd
credits.purchasedCredits were addedcredit_usd, kind (purchase)
job.completedA crawl (or other job) finished or was cancelledjob_id, kind, summary
job.failedA job failed (e.g. out of credits)job_id, kind, summary, error
api_key.leakedA key was found in public and revokedkey_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.