Watchlists and webhooks
Put advertisers on a watchlist and get told when ads start, stop, change or are removed from a library, by signed webhook, Slack, Discord or email.
A watchlist is a list of brands and advertisers we check on a schedule. After each check you receive one event per advertiser with the new, stopped, changed and removed ads. It can go to your own endpoint (signed), straight into a Slack or Discord channel, or to your inbox.
Create a watchlist
curl -X POST "https://api.adlibapi.com/v1/watchlists" \
-H "X-API-Key: $ADLIB_API_KEY" -H "Content-Type: application/json" \
-d '{"name": "Competitors",
"domains": ["nike.com", "adidas.com"],
"webhook_url": "https://hooks.example.com/adlib",
"interval_hours": 24}'For each domain we find the brand's own accounts on every platform, leave out agencies and resellers, watch the accounts together and add new ones as they appear. To leave an account out, pass exclude_advertisers or remove it later; it stays off.
You can also watch single accounts with "advertisers": ["meta:15087023444"]; find their ids with resolve. Add to an existing watchlist with POST /v1/watchlists/{id}/brands or POST /v1/watchlists/{id}/advertisers.
Your account limits the brands you watch over all your watchlists, and the shortest interval. A domain is one brand, with up to 25 accounts; a single advertiser also counts as one brand.
| Account | Brands | Shortest interval |
|---|---|---|
| On the free credits | 3 | 24 h |
| After the first credit pack | 250 | 6 h |
The first check of an advertiser is the baseline: it records the current ads and sends no event. We also read its ended ads once, as far as the library still shows them, so its history starts with more than what runs today.
The event
{
"event": "advertiser.changes",
"watchlist_id": "0b7c6a8e-1f2d-4c3b-9a8e-5d6f7a8b9c0d",
"advertiser_id": "meta:15087023444",
"crawled_at": "2026-10-27T08:00:00Z",
"summary": { "new": 2, "started": 0, "stopped": 1, "changed": 0, "removed": 1 },
"new": [ { "type": "discovered", "at": "...", "ad_id": "meta:...", "ad": { ... } } ],
"started": [],
"stopped": [ ... ],
"changed": [],
"removed": [ { "type": "removed", "at": "...", "ad_id": "meta:...", "ad": { ... } } ]
}removed lists ads the platform's own library no longer shows: taken down for a policy violation, deleted by the advertiser, or past the library's retention. We check stopped ads of watched advertisers one by one; two empty lookups at least 20 hours apart confirm a removal. The ad stays in AdLib with removed_from_library_at set, and you can list them with GET /v1/search?source=history&advertiser=<id>&removed=true.
Every request carries X-AdLib-Event, X-AdLib-Delivery (the delivery id) and X-AdLib-Signature.
Verify the signature
X-AdLib-Signature looks like t=1793102400,v1=5f2c…. v1 is the hex HMAC-SHA256 of "<t>.<raw body>" with your webhook secret (GET /v1/webhooks/secret):
import hashlib, hmac, time
def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t, sig = parts["t"], parts["v1"]
expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig) and abs(time.time() - int(t)) < toleranceUse the raw body as received, before parsing the JSON. Rotate the secret with POST /v1/webhooks/secret/rotate.
Test, inspect and redeliver
POST /v1/webhooks/testsends a signedwebhook.pingto a URL.GET /v1/webhooks/deliverieslists recent deliveries with status codes;GET /v1/webhooks/deliveries/{id}includes the payload.POST /v1/webhooks/deliveries/{id}/redeliverqueues a delivery again.
Failed deliveries are retried. Answer with a 2xx quickly and do the work afterwards.
Slack, Discord and email
Set webhook_url to a Slack incoming webhook (https://hooks.slack.com/...) or a Discord webhook (https://discord.com/api/webhooks/...) and we post a readable summary with up to five ads instead of the JSON event. No code needed.
For mail, set "email_alerts": true on create, or later:
curl -X PATCH "https://api.adlibapi.com/v1/watchlists/$WATCHLIST_ID" \
-H "X-API-Key: $ADLIB_API_KEY" -H "Content-Type: application/json" \
-d '{"email_alerts": true, "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX"}'The digest goes to your account's email after every check that found something. The first check of a new advertiser only records what is running and sends nothing. PATCH also renames a watchlist; "webhook_url": "" removes the webhook.
At a set time
By default a watchlist is checked whenever its interval is up, so alerts come at any hour. Set alert_time and timezone to put the checks on your local time: a daily list is checked at that time every day, a list with interval_hours 6 at that time and every 6 hours after it. Mails and webhooks go out right after each check, a few minutes past the time you set. Summer and winter time are taken into account.
curl -X PATCH "https://api.adlibapi.com/v1/watchlists/$WATCHLIST_ID" \
-H "X-API-Key: $ADLIB_API_KEY" -H "Content-Type: application/json" \
-d '{"alert_time": "08:00", "timezone": "America/Los_Angeles"}'timezone is an IANA name such as Europe/Berlin. "alert_time": "" goes back to checking whenever the interval is up. Both also work on create.
To see that mails reach you, send a test alert. It goes to the same address as real alerts, is free and works up to 5 times an hour:
curl -X POST "https://api.adlibapi.com/v1/watchlists/$WATCHLIST_ID/test-alert" -H "X-API-Key: $ADLIB_API_KEY"The answer says where it went and whether the mail server accepted it: {"status": "sent", "sent_to": ["[email protected]"], "email_alerts": true}. Check your spam folder if it doesn't arrive.
Without webhooks
Leave out webhook_url and poll GET /v1/advertisers/{id}/changes?since= instead. The watchlist still records every ad.