Webhooks

iGregulator delivers change alerts via HTTP POST to a URL you control. Nine event types (plus one reserved name), HMAC-SHA256 signed, up to seven delivery attempts — the first plus six retries — with jittered backoff. Sign up for alerts in the dashboard — no code needed, create a URL, select events, copy the secret once.

Just want to wire it up fast? Skip to /docs/webhooks/quickstart for a 2-minute tour using webhook.site as the receiver.

1. Event types

Ten dot-notation event names — nine sent today, one reserved. Subscribe to any subset per endpoint.

Event	Fires
license.status_changed	A scraper recorded a licence moving from one status to another — active, suspended, revoked, pending, surrendered, not_in_register, unknown. Both previous_status and new_status are always set. A move to expired sends license.expired instead, and a newly observed licence sends license.issued. Branch on new_status: only active means licensed, and surrendered / not_in_register are not revocations.
license.expiring_30d	Active licence with expiry_date exactly 30 days from now.
license.expiring_60d	Same, 60 days.
license.expiring_90d	Same, 90 days.
license.expired	A scraper recorded the licence’s status becoming expired — the regulator’s register said so (Expired, Lapsed, “not extended by the CGA”…). Sent instead of license.status_changed for that transition. An expiry_date passing on its own does not send it.
license.issued	New licence first observed in a scraper run. The only event for that first observation — no license.status_changed accompanies it.
regulatory_action.added	Fine / warning / revocation / licence_suspension entry added.
coverage.degraded	/v1/health/coverage transitions to degraded for a jurisdiction.
coverage.restored	/v1/health/coverage transitions back to healthy.
webhook.endpoint_degraded	Reserved — not sent yet. Accepted in an endpoint’s events list, but nothing emits it today. To notice a failing endpoint, poll GET /v1/webhooks/:id/deliveries?status=abandoned and watch for X-iGregulator-Missed-Deliveries on the deliveries you do receive (§3).

Subscribing to multiple expiry windows

Subscribing to all three (license.expiring_30d, _60d, _90d) delivers three separate webhooks per licence as it approaches expiry. By design — they’re semantically distinct warnings, not duplicates. Subscribe only to the warning period(s) you act on.

function onWebhook(event) {
  switch (event.event) {
    case 'license.expiring_90d':
      // Notify, no blocker — 3 months is plenty
      notifyCompliance(event.data);
      break;
    case 'license.expiring_60d':
      // Compose renewal paperwork
      kickoffRenewalFlow(event.data);
      break;
    case 'license.expiring_30d':
      // Escalate, block new referrals to the operator
      lockOperator(event.data);
      break;
  }
}

2. Envelope

Every event — production or test — carries the same outer shape:

{
  "event": "license.status_changed",
  "event_id": "evt_01HX8EGQK3J7WA6MYTP7ZGYF21",
  "api_version": "2026-04-20",
  "timestamp": "2026-04-20T14:32:00.000Z",
  "livemode": true,
  "data": {
    "license_id": "uuid",
    "license_number": "000000-R-000000-001",
    "operator_id": "uuid",
    "operator_slug": "example-operator-limited",
    "jurisdiction_code": "UKGC",
    "previous_status": "active",
    "new_status": "suspended",
    "changed_at": "2026-04-20T03:04:12.000Z",
    "source_url": "https://www.gamblingcommission.gov.uk/..."
  }
}

(An illustration — the licence and operator are placeholders, not a real event.)

• event_id — evt_ + a ULID, sorted lexicographically. Dedupe on this.
• data.previous_status on license.status_changed is never null: a licence’s first observation is license.issued (with data.status), not a status change.
• api_version — a date constant: every delivery today carries 2026-04-20. Pinning a subscriber to an older version when a data shape changes is planned, not built — there is one version, and no endpoint setting selects another.
• livemode — false only for test.ping events from the dashboard Test button.
• timestamp — when we emitted the event. Not when the change happened (that’s in data.*_at).

Regulatory action amounts

regulatory_action.added includes amount_minor_units — in the smallest currency unit (pence for GBP, cents for USD). £5 million = 5000000000. We store it this way so a £5M fine never gets confused with £5,000.

{
  "action_type": "fine",
  "amount_minor_units": 5000000000,
  "currency": "GBP"
}

3. Headers

Every delivery, including retries:

Content-Type: application/json
User-Agent: iGregulator-Webhook/1 (+https://igregulator.io)
X-iGregulator-Event: license.status_changed
X-iGregulator-Event-Id: evt_01HX8EGQK3J7WA6MYTP7ZGYF21
X-iGregulator-Timestamp: 1776717845
X-iGregulator-Delivery-Id: 3b1e2c4a-f8d1-4a7c-8b5f-111111111111
X-iGregulator-Attempt: 2
X-iGregulator-Signature: t=1776717845,v1=abcd…ef01

X-iGregulator-Attempt — the attempt number: 1 for the first delivery, 2–7 for retries. X-iGregulator-Missed-Deliveries: N is added to every delivery attempt to an endpoint that has had N deliveries abandoned (all 7 attempts exhausted) since its last successful one; it disappears once a delivery succeeds. Fetch the missed ones via GET /v1/webhooks/:id/deliveries?status=abandoned.

4. Signature verification

The X-iGregulator-Signature header is a Stripe-style CSV:

t=<unix-epoch-seconds>,v1=<hex>[,v1=<hex>…]

• t — the timestamp used in the HMAC input.
• v1 — HMAC-SHA256 hex digest. May appear multiple times when a secret rotation is in progress; each v1 is the signature computed with a different active secret. Accept the delivery if any v1 value matches.

Signed input = ${t}.${raw_body} — the HTTP body is included byte- for-byte; do not re-serialise the JSON before verifying, or whitespace drift will break the MAC.

Node.js

import crypto from 'node:crypto';

function verify(req, rawBody, secret) {
  const header = req.headers['x-igregulator-signature'];
  if (!header) return false;
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=')),
  );
  const signed = `${parts.t}.${rawBody}`;
  const expected = crypto.createHmac('sha256', secret)
    .update(signed).digest('hex');

  // Header may have several v1= values — iterate and accept any.
  const candidates = header
    .split(',')
    .filter((p) => p.startsWith('v1='))
    .map((p) => p.slice(3));
  return candidates.some((candidate) =>
    candidate.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(candidate), Buffer.from(expected)),
  );
}

Python

import hmac, hashlib

def verify(headers, raw_body: bytes, secret: str) -> bool:
    header = headers.get('x-igregulator-signature')
    if not header:
        return False
    parts = dict(p.split('=', 1) for p in header.split(','))
    signed = f"{parts['t']}.{raw_body.decode()}"
    expected = hmac.new(secret.encode(), signed.encode(), hashlib.sha256).hexdigest()
    candidates = [p[3:] for p in header.split(',') if p.startswith('v1=')]
    return any(hmac.compare_digest(c, expected) for c in candidates)

curl + jq

# Debug verification from a saved request. Pass raw body on stdin.
SIG_HEADER="t=1776717845,v1=abcd...ef01"
SECRET="whsec_..."
T=$(echo "$SIG_HEADER" | tr ',' '\n' | awk -F= '/^t/{print $2}')
EXPECTED=$(printf '%s.%s' "$T" "$(cat)" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')
echo "$SIG_HEADER" | tr ',' '\n' | grep "^v1=" | awk -F= '{print $2}' \
  | grep -Fqx "$EXPECTED" && echo "ok" || echo "mismatch"

Replay protection

Reject the delivery if |now - X-iGregulator-Timestamp| exceeds 300 seconds — an attacker who captured a delivery can’t re-send it an hour later. Our retries never push timestamps past this window (the worker re-signs on each attempt with the current time).

5. Retry policy

Failed deliveries retry on a jittered schedule:

Attempt	Delay after previous	With ± 20 % jitter
1	—	fired immediately
2	30 s	24 – 36 s
3	2 m	1:36 – 2:24 m
4	10 m	8 – 12 m
5	1 h	48 – 72 m
6	6 h	4.8 – 7.2 h
7	24 h	19.2 – 28.8 h
—	abandon after 7 total attempts

Failure = any non-2xx response or network error (DNS, timeout, TLS, connection reset). 3xx redirects are treated as failures on purpose — point your URL at the final destination. Following them silently would let an attacker redirect deliveries to an internal metadata service after the URL passed creation-time checks. Common gotcha: API gateways that issue a transparent https:// upgrade on http:// URLs — register the https:// form directly to avoid the redirect.

Timeout per attempt: 10 seconds. Long-running receivers should ack fast and process async (return 2xx immediately, queue the body for your worker).

6. Delivery guarantees

• At-least-once. A network blip may have us deliver the same event twice. Dedupe on event_id.
• No ordering. Events from different operators run independently; even events on the same operator can arrive out of order during a retry burst. Use data.*_at timestamps inside the payload to sequence consumer-side state.
• Scraper outages queue. If a jurisdiction’s scraper stalls, detected changes queue up and fire on the next successful run — no lost events, just a delayed batch.
• Retention: 30 days for both webhook_events (replay window) and webhook_deliveries (delivery history). Fetch deliveries via GET /v1/webhooks/:id/deliveries while they’re still in the window; older rows are pruned daily.

7. Integration patterns

Pattern A — Webhooks primary

The simplest setup. Create an endpoint, subscribe to events, process them in real time.

app.post('/igregulator-webhook', async (req, res) => {
  if (!verify(req, rawBody, process.env.WEBHOOK_SECRET)) {
    return res.status(400).send('bad signature');
  }
  res.sendStatus(200); // ACK fast, process async
  void queueForProcessing(req.body);
});

Pattern B — Polling fallback

Agent can’t accept inbound webhooks (locked-down corporate network, local dev). Use GET /v1/watchlist/events — see watchlist docs. Bootstrap with since=<ISO>, then switch to cursor pagination. No endpoint needed: polling returns the events for the operators on your watchlist.

Pattern C — Hybrid webhook + polling

Run both. Webhooks are the low-latency primary; polling covers the few-hour window where your receiver was down and deliveries might abandon. Because the same event_id ships on both channels, dedupe on it and there’s no double-processing.

Node.js

import Redis from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
const DEDUPE_TTL = 30 * 24 * 60 * 60; // match the 30-day event + delivery retention

async function processOnce(event) {
  // SET NX returns null if the key already exists.
  const set = await redis.set(
    `event_seen:${event.event_id}`, '1',
    'EX', DEDUPE_TTL, 'NX',
  );
  if (set === null) return; // already processed
  await handleEvent(event); // your business logic
}

// Webhook handler:
app.post('/webhook', async (req, res) => {
  if (!verify(req, rawBody, secret)) return res.sendStatus(400);
  res.sendStatus(200);
  await processOnce(req.body);
});

// Hourly polling fallback:
async function pollBackfill() {
  let cursor = await redis.get('watchlist:cursor');
  while (true) {
    const url = new URL('https://api.igregulator.io/v1/watchlist/events');
    if (cursor) url.searchParams.set('cursor', cursor);
    else url.searchParams.set('since', new Date(Date.now() - 3600_000).toISOString());
    url.searchParams.set('limit', '100');
    const r = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
    const { events, next_cursor, has_more } = await r.json();
    for (const event of events) await processOnce(event);
    if (next_cursor) {
      cursor = next_cursor;
      await redis.set('watchlist:cursor', cursor);
    }
    if (!has_more) break;
  }
}

Python

import os
import threading
from datetime import datetime, timedelta, timezone

import redis
import requests
from flask import Flask, abort, request

app = Flask(__name__)
r = redis.Redis.from_url(os.environ['REDIS_URL'], decode_responses=True)
API_KEY = os.environ['IGREGULATOR_API_KEY']
SECRET = os.environ['WEBHOOK_SECRET']
DEDUPE_TTL = 30 * 24 * 3600  # match the 30-day event + delivery retention

# verify() is the Python function from §4.

def handle_event(event):
    ...  # your business logic

def process_once(event):
    # SET NX returns None if key already exists.
    if r.set(f"event_seen:{event['event_id']}", '1',
             ex=DEDUPE_TTL, nx=True) is None:
        return  # already processed
    handle_event(event)  # your business logic

# Webhook handler (Flask):
@app.post('/webhook')
def webhook():
    if not verify(request.headers, request.get_data(), SECRET):
        abort(400)
    event = request.get_json()
    # ACK fast, process async (use a real queue in production)
    threading.Thread(target=process_once, args=(event,)).start()
    return '', 200

# Hourly backfill:
def poll_backfill():
    cursor = r.get('watchlist:cursor')
    while True:
        params = {'limit': 100}
        if cursor:
            params['cursor'] = cursor
        else:
            since = datetime.now(timezone.utc) - timedelta(hours=1)
            params['since'] = since.isoformat(timespec='seconds')
        resp = requests.get(
            'https://api.igregulator.io/v1/watchlist/events',
            headers={'Authorization': f'Bearer {API_KEY}'},
            params=params, timeout=10,
        ).json()
        for event in resp['events']: process_once(event)
        if resp.get('next_cursor'):
            cursor = resp['next_cursor']
            r.set('watchlist:cursor', cursor)
        if not resp.get('has_more'): break

8. Testing

• Dashboard Test button — fires a synthetic test.ping event at your endpoint. Does NOT create delivery history rows. Use during wiring to confirm the signature path.
• webhook.site — paste your URL there, hit Test, inspect headers + body. Fastest way to see what a delivery looks like before your server exists.
• ngrok / cloudflared — tunnel a local dev server to a public URL. http://localhost is blocked by our SSRF filter at creation time; a tunnel gives you a real routable host.

9. Secret rotation

Rotation overlap is 7 days. The rotation flow:

1. Click Rotate on the endpoint in the dashboard.
2. We issue a new secret and stamp the previous one with expires_at = NOW() + 7 days.
3. Deliveries sign with both secrets during the overlap — every delivery carries v1=<hex>,v1=<hex> in the signature header.
4. Update your server to accept the new secret. Existing code that uses the old one keeps verifying until day 7.
5. After day 7, the old secret expires and deliveries sign only with the new one.

Silent fail after rotation

If your server isn’t updated to accept the new secret before the old one expires (day 7), every delivery after that starts failing signature verification — silently, from your end, because we still deliver successfully (we don’t know your verification is wrong). If your receiver answers non-2xx on a bad signature (as the examples above do), the dashboard’s Deliveries modal shows a rising failure rate; it’s the canary. For a second layer, poll GET /v1/webhooks/:id/deliveries?status=abandoned and alert on X-iGregulator-Missed-Deliveries — the webhook.endpoint_degraded event is reserved and not sent yet.

10. Errors at creation time

A URL the SSRF policy rejects answers 400 invalid_query with details.field: "url" and one of these details.reason values (the same checks run on PATCH, and again before every delivery):

• private_ip_blocked — the host resolved to a private / loopback / link-local IP (including 169.254.169.254, AWS + GCP metadata). Use a public host or a tunnel.
• invalid_scheme — only http:// and https:// are accepted; https strongly preferred.
• blocked_hostname — a blocklisted name such as localhost.
• unresolvable_host — the hostname doesn’t resolve.
• invalid_url / empty_host — not an absolute URL, or no hostname.

Other creation errors:

• 400 invalid_query + details.reason: invalid_event_type — You passed an unrecognised event name. Compare against the list in §1.
• 400 invalid_query + details.reason: invalid_input — the body isn’t { url, events: [...], watchlist_only?, description? }.
• 403 quota_exceeded + details.reason: webhook_quota_exceeded — You hit your plan’s number of active endpoints. Pause or delete an endpoint, or email founder@igregulator.io if you need a higher cap.

11. Best practices

• Respond 2xx in < 5 seconds, process async. We time out at 10 s; if your receiver regularly takes 5+ s you’ll start hitting retries.
• Verify every delivery. Skip only for test.ping if you treat test events as connectivity checks and not real data.
• Dedupe on event_id. Always. At-least-once delivery means duplicates will happen eventually.
• Don’t assume ordering. Use data.*_at timestamps.
• Keep a polling fallback for critical paths — see Pattern C.
• Watch for abandoned deliveries. Poll GET /v1/webhooks/:id/deliveries?status=abandoned and alert when X-iGregulator-Missed-Deliveries shows up, so you don’t hear about a failing endpoint from a missing downstream action. (webhook.endpoint_degraded is reserved and not sent yet.)