Docs · Reference · Webhooks

Webhooks

Receive every check decision in your own infrastructure. Useful for audit trails, fraud-team dashboards, and routing high-risk signups into review queues.

Events

Event	Fires when
`check.created`	Every `/v1/check` call, regardless of verdict.
`check.blocked`	Score ≥ block threshold.
`check.flagged`	Score between flag and block thresholds.
`user.first_seen`	A brand-new `tellr_id` is created.
`user.repeat_detected`	An existing `end_user` matches a composite ID.

Delivery

Each event POSTs a JSON body to your URL with an X-Tellr-Signature header containing an HMAC-SHA-256 of the raw body, keyed by your webhook secret. Retries follow exponential backoff for up to 24 hours.

Signature verification

import crypto from 'crypto';

const sig = req.headers['x-tellr-signature'] as string;
const computed = crypto
  .createHmac('sha256', process.env.TELLR_WEBHOOK_SECRET!)
  .update(req.rawBody)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(computed))) {
  return res.status(400).end();
}

Sample payload

json

{
  "event": "check.blocked",
  "id": "evt_2K9d3f8",
  "created_at": "2026-05-19T18:32:11Z",
  "data": {
    "check_id": "chk_2K9d3f8",
    "tellr_id": "194827361092847362",
    "verdict": "block",
    "score": 87
  }
}