Skip to content

Notifications API

All endpoints on this page need the scope manage:notifications. The channels you can use depend on your plan (notificationChannels in GET /v1/plan); a channel the plan does not include answers 403 entitlement: notification_channels. See Notifications for how alerts work, and Webhook events for the payloads.

{
"id": 4,
"label": "Ops webhook",
"channel": "webhook",
"destination": { "url": "https://hooks.example.com/ad80", "secrets": [{ "id": "s_a1b2c3d4", "created_at": "2026-10-26T10:00:00Z" }] },
"event_types": ["creative.violation"],
"filters": { "app_ids": ["com.example.news"], "rule_ids": ["no-alcohol"], "min_score": 0.7 },
"mode": "immediate",
"language": "en",
"attach_image": false,
"enabled": true,
"verified_at": "2026-10-26T10:02:11Z",
"created_by": "user:31",
"created_at": "2026-10-26T10:00:00Z",
"updated_at": "2026-10-26T10:02:11Z"
}
FieldValues
channelemail or webhook.
destinationE-mail: {"to": "alerts@example.com"}. Webhook: {"url": "https://..."}; secrets are never shown, only their ids and dates.
event_typesAt least one of creative.violation, creative.classified, key.expiring.
filtersOptional. app_ids and rule_ids (up to 100 each; empty = all), min_score (0 to 1).
modeimmediate (default), digest_hourly or digest_daily.
languageen (default) or ar: the language of the message.
attach_imageWebhooks: also include the creative image, base64-encoded, in the payload.
enabledfalse pauses the subscription.
verified_atnull until the destination is verified. An unverified subscription receives only its verification message.

An organization can have up to 50 subscriptions.

GET /v1/notifications/subscriptions

{"subscriptions": [ ... ], "channels": ["email", "webhook"]}; channels lists the channels available on the server.

POST /v1/notifications/subscriptions
Terminal window
curl -s -X POST https://api.ad80.dev/v1/notifications/subscriptions \
-H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \
-d '{
"label": "Ops webhook",
"channel": "webhook",
"destination": {"url": "https://hooks.example.com/ad80"},
"event_types": ["creative.violation"],
"mode": "immediate",
"language": "en"
}'

201:

{
"subscription": { "id": 4, "channel": "webhook", "verified_at": null, "...": "..." },
"secrets": { "secret": "whsec_YOUR_SIGNING_SECRET" }
}

For a webhook, secrets.secret is the signing secret. It is shown only in this response; store it to verify signatures. Webhook URLs must be https and resolve to public addresses; private, loopback, link-local and metadata addresses are refused (400).

PATCH /v1/notifications/subscriptions/{id}

Any of label, destination, event_types, filters, mode, language, attach_image, enabled. Changing the destination requires verifying it again. Re-enabling a subscription on a channel your plan no longer includes is refused.

DELETE /v1/notifications/subscriptions/{id}
POST /v1/notifications/subscriptions/{id}/verify

Sends the verification message (no body). 202:

{ "method": "link", "expires_at": "2026-10-28T10:00:00Z" }
  • E-mail (method: link): the address receives a confirmation e-mail. Opening the link shows a page with a Confirm button; pressing it verifies the subscription.
  • Webhook (method: code): your endpoint receives a notify.verify event whose data.code is a one-time code (starting with vc_). Send it back:
POST /v1/notifications/subscriptions/{id}/confirm
Terminal window
curl -s -X POST https://api.ad80.dev/v1/notifications/subscriptions/4/confirm \
-H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \
-d '{"code": "vc_THE_CODE_YOU_RECEIVED"}'

{"verified": true}. The verification expires after 48 hours (expires_at); start it again if needed. Verifying is rate limited: 429 with Retry-After when you try too often.

POST /v1/notifications/subscriptions/{id}/test

Queues a notify.test message to a verified subscription. 202 {"delivery_id": 991}. Follow it in the delivery log.

POST /v1/notifications/subscriptions/{id}/rotate-secret

Adds a new signing secret and returns it once:

{ "secrets": { "secret": "whsec_NEW_SECRET" }, "note": "both the new and the previous secret sign deliveries until you call retire-secrets" }
POST /v1/notifications/subscriptions/{id}/retire-secrets

Keeps only the newest secret. 204. See Secret rotation.

GET /v1/notifications/deliveries
QueryMeaning
statusqueued, claimed, delivered, dead, digest_pending, digested or skipped.
subscriptionA subscription id.
limit1 to 500, default 100.
{
"deliveries": [
{
"id": 991,
"event_id": 2,
"event_type": "creative.violation",
"subscription_id": 4,
"status": "delivered",
"attempts": 1,
"next_attempt_at": "2026-10-26T14:03:00Z",
"last_error": "",
"created_at": "2026-10-26T14:03:00Z",
"delivered_at": "2026-10-26T14:03:01Z",
"delivery_mode": "immediate"
}
]
}

delivery_mode is immediate or digest (a digest subscription, or an alert held for the digest because the monthly expedited allowance was used up). dead means AD80 gave up (see Retries).

GET /v1/notifications/deliveries/{id}/attempts

Every attempt: attempt, started_at, duration_ms, outcome (ok, transient, permanent, delayed), status_code, response (truncated) and error.

POST /v1/notifications/deliveries/{id}/redeliver

Queues a finished delivery (delivered, dead or skipped) again with the same delivery id, so your receiver can de-duplicate it. 202 {"delivery_id": 991, "status": "queued"}; 404 when it is still queued.