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.
The subscription object
Section titled “The subscription object”{ "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"}| Field | Values |
|---|---|
channel | email or webhook. |
destination | E-mail: {"to": "alerts@example.com"}. Webhook: {"url": "https://..."}; secrets are never shown, only their ids and dates. |
event_types | At least one of creative.violation, creative.classified, key.expiring. |
filters | Optional. app_ids and rule_ids (up to 100 each; empty = all), min_score (0 to 1). |
mode | immediate (default), digest_hourly or digest_daily. |
language | en (default) or ar: the language of the message. |
attach_image | Webhooks: also include the creative image, base64-encoded, in the payload. |
enabled | false pauses the subscription. |
verified_at | null until the destination is verified. An unverified subscription receives only its verification message. |
An organization can have up to 50 subscriptions.
List subscriptions
Section titled “List subscriptions”{"subscriptions": [ ... ], "channels": ["email", "webhook"]}; channels lists the channels available on the
server.
Create a subscription
Section titled “Create a subscription”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).
Update or delete
Section titled “Update or delete”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.
Verify a destination
Section titled “Verify a destination”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 anotify.verifyevent whosedata.codeis a one-time code (starting withvc_). Send it back:
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.
Send a test
Section titled “Send a test”Queues a notify.test message to a verified subscription. 202 {"delivery_id": 991}. Follow it in the delivery
log.
Rotate the webhook secret
Section titled “Rotate the webhook 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" }Keeps only the newest secret. 204. See Secret rotation.
Deliveries
Section titled “Deliveries”| Query | Meaning |
|---|---|
status | queued, claimed, delivered, dead, digest_pending, digested or skipped. |
subscription | A subscription id. |
limit | 1 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).
Every attempt: attempt, started_at, duration_ms, outcome (ok, transient, permanent, delayed),
status_code, response (truncated) and error.
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.