Webhooks

Webhooks push events to your endpoint instead of you polling. Create a subscription with a delivery URL and AskThis sends a signed POST when a subscribed event fires. Manage them under Settings → Webhooks (the signing secret is shown once at creation) or over the API.

Event catalog

Event	Fires when
scan.completed	An onboarding or re-scan finishes and prompts are ready
scan.failed	A scan job errors out
credits.low	Your balance drops below the low-balance threshold
credits.depleted	Your balance hits zero
citation.detected	Citation Monitor finds your site cited by an AI engine
subscription.updated	Your plan is created, upgraded, downgraded, or cancelled
invoice.paid	A gateway invoice is paid
site.installed	A site’s widget is verified live for the first time

Subscribing to an event outside this list is rejected with a 422. Payloads are { event, payload, timestamp } (ISO-8601 timestamp).

Verify every delivery

Each delivery is signed with HMAC-SHA256 over the raw request body, using your subscription secret; the hex signature arrives in the X-AskThis-Signature header. Recompute and compare with a timing-safe check before trusting it:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Delivery guarantees

• Signed — always verify; reject on mismatch (401).
• Time-boxed — each attempt times out after 5 seconds. Queue the work and return 200 fast.
• Retried — failed deliveries are retried, so make your handler idempotent (dedupe on the event). Inspect recent attempts via the deliveries endpoint, or fire a sample with the test endpoint.