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_statusiscompletedorpartial).scanning.scan.failed— a scan failed terminally.scanning.tags.detected— one or more tags were attached to a scan (payload carriestag_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 onscan_idfor this event). - Nothing when a crawl captured no image at all — a hard navigation
failure sends
scanning.scan.failedinstead.
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"
}
}
| Field | Meaning |
|---|---|
version | Envelope schema version. Matches the X-Webhook-Api-Version header; a bump signals a breaking change. |
event_type | The event name, e.g. scanning.scan.completed. Same value as the X-Webhook-Event header. |
event_id | Stable UUID for this event. Same value as the X-Webhook-Event-Id header. Use it to deduplicate (see below). |
occurred_at | ISO-8601 UTC timestamp of when the event occurred. |
data | Event-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:
| Header | Value |
|---|---|
Content-Type | application/json. |
User-Agent | Kaminari.Ad-Webhook/1.0. |
X-Webhook-Api-Version | Integer schema version; matches version in the body. |
X-Webhook-Event | The event type, e.g. scanning.scan.completed. |
X-Webhook-Event-Id | Stable event UUID — your idempotency key. Identical to event_id in the body, and unchanged across redeliveries. |
X-Webhook-Timestamp | Unix time (whole seconds) at signing. Also folded into the signed input for replay protection. |
X-Webhook-Signature | sha256=<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:
- Take the
X-Webhook-Timestampheader value (a string of digits) and the raw request body bytes exactly as received. - Build the signed input by concatenating the timestamp, a single
literal
.(dot), then the raw body bytes — i.e."{timestamp}." + body. - Compute
HMAC-SHA256(key = secret, message = signed_input)and hex-encode it (lowercase). - 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-Timestampis 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 event | What happens |
|---|---|
| 0-24h | Retried with growing backoff; new events keep buffering |
| 24h | Delivery abandoned; the event stays replayable |
| 7 days | The 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:
| Field | Meaning |
|---|---|
failing_since | Start of the current uninterrupted failure run, null when healthy. Subtract from now to get the outage length. |
paused_until | End of the current delivery cooldown, null when not pausing. A value in the past simply means the cooldown has elapsed. |
last_delivery_at | Timestamp of the most recent attempt. |
last_delivery_status | HTTP status of the most recent attempt. |
success_rate_7d | Share 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.