Skip to content

Webhook events

AD80 delivers each notification to your webhook as an HTTPS POST with a JSON body.

HeaderValue
Content-Typeapplication/json
User-AgentAD80-Notify/1
X-AD80-EventThe event type: creative.violation, creative.classified, key.expiring, digest, notify.test or notify.verify.
X-AD80-DeliveryThe delivery id. A retry or a redelivery keeps the same id.
Idempotency-KeyThe same value as X-AD80-Delivery.
X-AD80-TimestampUnix time (seconds) when this attempt was signed.
X-AD80-Signaturev1=<hex>, one entry per active secret, comma separated. See Verify signatures.

Every payload has the same top level:

FieldMeaning
idThe delivery id (a string, equal to X-AD80-Delivery).
typeThe event type.
languageen or ar, from the subscription.
summaryA readable text version of the message, in that language.
event_id, created_atThe event’s id and time (single events).
dataThe event data (below).
imageFor creative events: url (a signed image link valid for 7 days) and, when the subscription has attach_image, base64 (the PNG).
expeditedPresent and false when the alert was held for a digest because the monthly expedited allowance was used up.
{
"id": "42",
"type": "creative.violation",
"language": "en",
"event_id": 2,
"created_at": "2026-10-26T14:03:00Z",
"data": {
"appId": "com.example.news",
"contentHash": "ad80px1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"violates": true,
"verdictId": 5,
"scores": [
{ "rule_id": "no-gambling", "score": 0.91, "reason": "casino chips" },
{ "rule_id": "no-alcohol", "score": 0.12, "reason": "" },
{ "rule_id": "no-weapons", "score": 0.72, "reason": "rifle" }
],
"placementId": "MainActivity/banner_top",
"mediationPlatform": "admob",
"network": { "canonicalId": "meta", "adSourceName": "Meta Audience Network" }
},
"image": {
"url": "https://api.ad80.dev/v1/creatives/ad80px1:aaaa...aaaa/image?exp=1762092180&org=7&sig=..."
},
"summary": "A creative in com.example.news violates 2 rule(s): no-gambling 0.91, no-weapons 0.72.\n\nApp: com.example.news\n..."
}

scores lists every rule of the policy with its score from 0 to 1, and a reason for the rules that are broken. Which rules count as violated is decided by AD80; use the dashboard or GET /v1/creatives/{id} for the violates flag per rule.

Same data as creative.violation, with violates true or false. Sent for every classification of a creative your subscription’s filters match.

{
"id": "43",
"type": "key.expiring",
"language": "en",
"event_id": 6,
"created_at": "2026-10-26T14:03:00Z",
"data": {
"keyKind": "ingest",
"keyId": "ik_3",
"keyLabel": "prod",
"keyPrefix": "ad80_ik_Ab3",
"appId": "com.example.news",
"expiresAt": "2026-10-30T09:00:00Z"
},
"summary": "The ingest key \"prod\" (ad80_ik_Ab3...) for com.example.news expires on 2026-10-30 09:00 UTC. Rotate it before then. ..."
}

A digest subscription (or an alert held back after the expedited allowance) receives several events in one message:

{
"id": "9",
"type": "digest",
"language": "en",
"count": 2,
"events": [
{ "id": 2, "type": "creative.violation", "created_at": "2026-10-26T14:03:00Z", "data": { "appId": "com.example.news", "...": "..." } },
{ "id": 6, "type": "key.expiring", "created_at": "2026-10-26T14:03:00Z", "data": { "keyId": "ik_3", "...": "..." } }
],
"summary": "2 notifications since the last digest. ..."
}

Sent when you press Send test or call the test endpoint:

{
"id": "44",
"type": "notify.test",
"language": "en",
"event_id": 7,
"created_at": "2026-10-26T14:03:00Z",
"data": { "label": "ops", "subscriptionId": 4 },
"summary": "This is a test notification from AD80 for \"ops\". Your destination works. ..."
}

The first message to a new webhook. Its delivery id is verify-<subscription id>.

{
"id": "verify-4",
"type": "notify.verify",
"language": "en",
"event_id": 0,
"created_at": "2026-10-26T14:03:00Z",
"data": { "subscription_id": 4, "code": "vc_THE_CODE" },
"summary": "Confirm this destination to receive AD80 notifications.\nCode: vc_THE_CODE\n..."
}

Send data.code back to confirm the subscription; see Verify a destination.

  • Parse fields you need and ignore unknown ones: new fields may be added.
  • summary is for people; do not parse it.
  • Verify the signature on the raw body before you parse it.