Kaminari Ad

Webhooks

Subscribe to scan and alert events with signed, retried payloads — and wire them into your own systems.

Webhooks push events to your endpoint instead of making you poll. They are the recommended way to react to scans and alerts in real time.

Creating an endpoint

Add an endpoint under Account -> Webhooks (or via the API). Choose which event types it receives. Kaminari Ad generates a signing secret for the endpoint.

Event types

Subscribe to any of (the live list is at GET /api/v1/webhooks/event-types):

  • scanning.scan.created — a scan was registered and queued.
  • scanning.screenshot.captured — the crawl stored a screenshot; fires minutes before the scan completes (see below).
  • scanning.scan.completed — a scan finished (final_status is completed or partial).
  • scanning.scan.failed — a scan failed terminally.
  • scanning.tags.detected — one or more tags were attached to a scan (payload carries tag_slugs).
  • alerting.alert.created — a policy-violation alert was raised from a scan's tags.

Payloads carry identifiers (scan_id, organization_id, campaign_id, …), not the full scan object — fetch the scan via GET /api/v1/scans/{id} when you need its detail. The one exception is scanning.screenshot.captured, which carries ready-to-use URLs.

Reacting before a scan completes

A scan is only completed once classification has run, which typically takes several minutes after the page itself was captured. If you show captures to human moderators, subscribe to scanning.screenshot.captured instead of waiting: it is emitted in the same database transaction that ends the crawl, so it always reaches the queue before scanning.scan.completed for that scan.

{
  "scan_id": "11111111-1111-1111-1111-111111111111",
  "organization_id": "22222222-2222-2222-2222-222222222222",
  "campaign_id": "33333333-3333-3333-3333-333333333333",
  "run_id": null,
  "is_recheck": false,
  "page_title": "Example landing page",
  "screenshot_url": "https://app.kaminari.ad/api/v1/scans/11111111-1111-1111-1111-111111111111/screenshot",
  "creative_screenshot_url": null,
  "report_url": "https://app.kaminari.ad/scans/11111111-1111-1111-1111-111111111111",
  "public_report_url": "https://app.kaminari.ad/public/scans/11111111-1111-1111-1111-111111111111"
}

screenshot_url is the landing capture, creative_screenshot_url the rendered ad creative (ad-tag and VAST scans). Either can be null — never both, so branch on which one is present rather than assuming a landing image. Both are image URLs you can fetch directly (add ?w=<100..1200> for a thumbnail; outside that range the request is rejected); a Bearer token is accepted but not required, since the unguessable scan id is what protects them — treat the URLs themselves as secrets. report_url needs a dashboard login; public_report_url is shareable as-is.

is_recheck is part of the shared scan envelope and is always false here — a recheck never re-crawls, so it never captures a new screenshot. Don't branch on it for this event.

What to expect:

  • Every scan kind that captures something — url, ad_tag, vast, and discovered-ad children.
  • Once per crawl. A recheck re-runs the checkers over the artifacts the original crawl produced without re-crawling, so it does not send a second copy; retries and manual replays can, like any event, so deduplicate on event_id (or on scan_id for this event).
  • Nothing when a crawl captured no image at all — a hard navigation failure sends scanning.scan.failed instead.

Ordering is guaranteed only at emission: a retry of the earlier event can still arrive after a later one, so treat the two events as independent rather than as a sequence.

Delivery envelope

Every delivery is an HTTP POST with a JSON body. The body is a stable envelope; the event-specific identifiers live under data:

{
  "version": 1,
  "event_type": "scanning.scan.completed",
  "event_id": "0bdd6d6a-5d8d-4a6d-9e1e-26b21f1a8a01",
  "occurred_at": "2026-04-18T12:00:00+00:00",
  "data": {
    "scan_id": "11111111-1111-1111-1111-111111111111",
    "organization_id": "22222222-2222-2222-2222-222222222222",
    "campaign_id": "33333333-3333-3333-3333-333333333333",
    "final_status": "completed"
  }
}
FieldMeaning
versionEnvelope schema version. Matches the X-Webhook-Api-Version header; a bump signals a breaking change.
event_typeThe event name, e.g. scanning.scan.completed. Same value as the X-Webhook-Event header.
event_idStable UUID for this event. Same value as the X-Webhook-Event-Id header. Use it to deduplicate (see below).
occurred_atISO-8601 UTC timestamp of when the event occurred.
dataEvent-specific identifiers. Fetch full objects via the REST API when you need detail.

The body is serialized compactly (no extra whitespace, keys sorted). Always verify the signature against the exact raw bytes you received — never re-serialize the JSON first, or you may change the bytes and break the signature.

Delivery headers

Every delivery carries these headers:

HeaderValue
Content-Typeapplication/json.
User-AgentKaminari.Ad-Webhook/1.0.
X-Webhook-Api-VersionInteger schema version; matches version in the body.
X-Webhook-EventThe event type, e.g. scanning.scan.completed.
X-Webhook-Event-IdStable event UUID — your idempotency key. Identical to event_id in the body, and unchanged across redeliveries.
X-Webhook-TimestampUnix time (whole seconds) at signing. Also folded into the signed input for replay protection.
X-Webhook-Signaturesha256=<hex> — the HMAC-SHA256 signature (see below).

There is no attempt-count header; redeliveries are identified by the unchanged X-Webhook-Event-Id.

Verifying signatures

Each delivery carries exactly one signature in the X-Webhook-Signature header, formatted as sha256= followed by a lowercase hex digest:

X-Webhook-Signature: sha256=<lowercase-hex>

To verify it:

  1. Take the X-Webhook-Timestamp header value (a string of digits) and the raw request body bytes exactly as received.
  2. Build the signed input by concatenating the timestamp, a single literal . (dot), then the raw body bytes — i.e. "{timestamp}." + body.
  3. Compute HMAC-SHA256(key = secret, message = signed_input) and hex-encode it (lowercase).
  4. Compare it against the hex after the sha256= prefix using a constant-time comparison.

Specifics that matter for a byte-exact implementation:

  • The digest is hex, not base64.
  • The signing secret is used as raw UTF-8 — the exact string shown to you once at creation/rotation. It is not base64-decoded and has no whsec_-style prefix.
  • One signature per delivery. There is no comma- or space-separated list and no v1=/v2= scheme. During secret rotation the new secret takes effect immediately and the old one stops working at once — there is no overlap window with two simultaneously valid signatures, so rotate when you can briefly tolerate verification failures, or pause the endpoint first.
  • Replay protection is your responsibility. The timestamp is folded into the signature so it can't be tampered with, but Kaminari Ad does not enforce a freshness window — reject deliveries whose X-Webhook-Timestamp is too far from your clock (a tolerance of around five minutes is typical).

Python

import hmac, hashlib

def verify(secret: str, timestamp: str, raw_body: bytes, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    got = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, got)

Node.js

const crypto = require("crypto");

function verify(secret, timestamp, rawBody, signatureHeader) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");
  const got = signatureHeader.replace(/^sha256=/, "");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));
}

PHP

function verify(string $secret, string $timestamp, string $rawBody, string $signatureHeader): bool {
    $expected = hash_hmac("sha256", $timestamp . "." . $rawBody, $secret);
    $got = preg_replace("/^sha256=/", "", $signatureHeader);
    return hash_equals($expected, $got);
}

Go

func Verify(secret, timestamp string, rawBody []byte, signatureHeader string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(timestamp + "."))
    mac.Write(rawBody)
    expected := hex.EncodeToString(mac.Sum(nil))
    got := strings.TrimPrefix(signatureHeader, "sha256=")
    return hmac.Equal([]byte(expected), []byte(got))
}

Worked example

Use this fixed vector to validate your implementation byte-for-byte. The same inputs always produce the same signature.

  • Signing secret: wh-secret-fixture
  • X-Webhook-Timestamp: 1776513600
  • Raw request body (162 bytes, exactly as sent on the wire — no whitespace, keys sorted):
{"data":{"scan_id":"42"},"event_id":"00000000-0000-0000-0000-000000000001","event_type":"scanning.scan.completed","occurred_at":"2026-04-18T12:00:00","version":1}

The signed input is 1776513600. followed by those body bytes. Feeding that to HMAC-SHA256 with the secret above yields:

X-Webhook-Signature: sha256=61c47e96810ef5df9f0454eab172e3867435859905a7993b8c1bc1bc95929a2a

The complete header block for this delivery:

Content-Type: application/json
User-Agent: Kaminari.Ad-Webhook/1.0
X-Webhook-Api-Version: 1
X-Webhook-Event: scanning.scan.completed
X-Webhook-Event-Id: 00000000-0000-0000-0000-000000000001
X-Webhook-Timestamp: 1776513600
X-Webhook-Signature: sha256=61c47e96810ef5df9f0454eab172e3867435859905a7993b8c1bc1bc95929a2a

If your implementation reproduces that exact signature for this input, it is byte-compatible with Kaminari Ad.

Retries, timeouts, and idempotency

A delivery is successful when your endpoint returns a 2xx status (200-299) within the timeout. The response body is ignored.

Per attempt, Kaminari Ad waits up to 5 seconds to connect and 10 seconds for the full response. Every non-2xx response and every transport error is retried — including 4xx. A load balancer answering 404 or 405 mid-reconfiguration is indistinguishable from a genuinely wrong path, so we keep trying rather than discard your event.

There is no status code you can return to make us stop, 410 Gone included. To stop delivery, disable or delete the endpoint from the dashboard or via the API — that is the only signal we treat as final.

Retries use exponential backoff (~30s, ~60s, ~120s, …) capped at 1 hour, and continue for up to 24 hours, measured from the event for a normal delivery and from the replay for a replayed one. After that the event is abandoned, but it is still available for replay from the dashboard for 7 days after it occurred. Replaying an abandoned event gives it a full fresh 24-hour window, so a backlog recovered days later still gets delivered.

Elapsed since the eventWhat happens
0-24hRetried with growing backoff; new events keep buffering
24hDelivery abandoned; the event stays replayable
7 daysThe event is deleted and can no longer be replayed

While your endpoint is down

The endpoint stays enabled and every new event is buffered, so nothing is lost. To avoid hammering a dead endpoint, deliveries pause between attempts for a cooldown that grows from 1 minute to 30 minutes; a single 2xx response ends the outage and the buffered backlog is delivered automatically. No action is needed on your side.

Two emails go to everyone in your org who can manage webhooks:

  • after 1 hour of uninterrupted failures — a warning, while events are still buffering;
  • after 24 hours without a single 2xx — the endpoint is switched off and new events stop being buffered.

Once switched off, re-enable the endpoint from the dashboard and then replay the buffered events from the same page, in that order.

Delivery is at-least-once, so you may receive the same event more than once (a retry, or a manual replay from the dashboard). Every copy carries the same X-Webhook-Event-Id / event_id — persist processed ids and skip duplicates.

Checking health from the API

GET /api/v1/webhooks and GET /api/v1/webhooks/{id} return a health object you can poll instead of waiting for the emails:

FieldMeaning
failing_sinceStart of the current uninterrupted failure run, null when healthy. Subtract from now to get the outage length.
paused_untilEnd of the current delivery cooldown, null when not pausing. A value in the past simply means the cooldown has elapsed.
last_delivery_atTimestamp of the most recent attempt.
last_delivery_statusHTTP status of the most recent attempt.
success_rate_7dShare of successful attempts over the last 7 days.

failing_since moving from null to a timestamp is the earliest machine-readable signal that we are struggling to reach you; it clears on the first 2xx.

Debugging

The dashboard lists recent delivery attempts with status and response, and lets you replay a delivery or send a test event so you can validate your handler end to end.

Common use

Wire scanning.tags.detected or alerting.alert.created into your bidder's block-list, your ticketing system, or a data warehouse. See Bidder block-list automation.

← All documentation