Watchlists und Webhooks
Setz Werbetreibende auf eine Watchlist und erfahre, wenn Anzeigen starten, stoppen, sich ändern oder aus einer Bibliothek entfernt werden, per signiertem Webhook, Slack, Discord oder E-Mail.
Eine Watchlist ist eine Liste von Marken und Werbetreibenden, die wir nach Zeitplan prüfen. Nach jedem Check bekommst du ein Event pro Werbetreibendem mit den neuen, gestoppten, geänderten und entfernten Anzeigen. Es kann an deinen eigenen Endpoint gehen (signiert), direkt in einen Slack- oder Discord-Channel oder in dein Postfach.
Eine Watchlist anlegen
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}'Für jede Domain finden wir die eigenen Konten der Marke auf jeder Plattform, lassen Agenturen und Reseller weg, beobachten die Konten gemeinsam und nehmen neue auf, sobald sie auftauchen. Willst du ein Konto ausschließen, übergib exclude_advertisers oder entferne es später. Es bleibt dann draußen.
Du kannst auch einzelne Konten beobachten, mit "advertisers": ["meta:15087023444"]. Ihre IDs findest du mit Resolve. Zu einer bestehenden Watchlist fügst du mit POST /v1/watchlists/{id}/brands oder POST /v1/watchlists/{id}/advertisers etwas hinzu.
Dein Konto begrenzt, wie viele Marken du über alle Watchlists hinweg beobachtest, und das kürzeste Intervall. Eine Domain ist eine Marke mit bis zu 25 Konten. Ein einzelner Werbetreibender zählt ebenfalls als eine Marke.
| Konto | Marken | Kürzestes Intervall |
|---|---|---|
| Mit den kostenlosen Credits | 3 | 24 h |
| Nach dem ersten Credit-Paket | 250 | 6 h |
Der erste Check eines Werbetreibenden ist die Ausgangsbasis: Er speichert die aktuellen Anzeigen und schickt kein Event. Wir lesen dabei auch einmal seine beendeten Anzeigen, soweit die Bibliothek sie noch zeigt. So beginnt sein Verlauf mit mehr als dem, was heute läuft.
Das 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 listet Anzeigen, die die Bibliothek der Plattform selbst nicht mehr zeigt: wegen eines Richtlinienverstoßes entfernt, vom Werbetreibenden gelöscht oder älter als die Aufbewahrungsfrist der Bibliothek. Gestoppte Anzeigen beobachteter Werbetreibender prüfen wir einzeln. Zwei leere Abfragen im Abstand von mindestens 20 Stunden bestätigen eine Entfernung. Die Anzeige bleibt in AdLib mit gesetztem removed_from_library_at, und du kannst sie mit GET /v1/search?source=history&advertiser=<id>&removed=true auflisten.
Jede Anfrage enthält X-AdLib-Event, X-AdLib-Delivery (die ID der Zustellung) und X-AdLib-Signature.
Die Signatur prüfen
X-AdLib-Signature sieht so aus: t=1793102400,v1=5f2c…. v1 ist der HMAC-SHA256 als Hex von "<t>.<raw body>" mit deinem 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)) < toleranceNimm den Body genau so, wie er ankommt, bevor du das JSON parst. Das Secret rotierst du mit POST /v1/webhooks/secret/rotate.
Testen, prüfen und erneut zustellen
POST /v1/webhooks/testschickt ein signierteswebhook.pingan eine URL.GET /v1/webhooks/deliverieslistet die letzten Zustellungen mit Statuscodes,GET /v1/webhooks/deliveries/{id}enthält auch die Payload.POST /v1/webhooks/deliveries/{id}/redeliverstellt eine Zustellung erneut in die Warteschlange.
Fehlgeschlagene Zustellungen werden wiederholt. Antworte schnell mit einem 2xx und erledige die Arbeit danach.
Slack, Discord und E-Mail
Setz webhook_url auf einen Slack-Incoming-Webhook (https://hooks.slack.com/...) oder einen Discord-Webhook (https://discord.com/api/webhooks/...). Wir posten dann statt des JSON-Events eine lesbare Zusammenfassung mit bis zu fünf Anzeigen. Ohne Code.
Für E-Mails setzt du "email_alerts": true beim Anlegen oder später:
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"}'Die Zusammenfassung geht nach jedem Check, der etwas gefunden hat, an die E-Mail-Adresse deines Kontos. Mit PATCH benennst du eine Watchlist auch um. "webhook_url": "" entfernt den Webhook.
Ohne Webhooks
Lass webhook_url weg und frag stattdessen regelmäßig GET /v1/advertisers/{id}/changes?since= ab. Die Watchlist speichert trotzdem jede Anzeige.