Docs

Listes de suivi et webhooks

Ajoutez des annonceurs à une liste de suivi et soyez prévenu quand des publicités démarrent, s’arrêtent, changent ou sont retirées d’une bibliothèque, par webhook signé, Slack, Discord ou e-mail.

Une liste de suivi est une liste de marques et d’annonceurs que nous vérifions à intervalle régulier. Après chaque vérification, vous recevez un événement par annonceur avec les publicités nouvelles, arrêtées, modifiées et retirées. Il peut partir vers votre propre endpoint (signé), directement dans un canal Slack ou Discord, ou dans votre boîte mail.

Créer une liste de suivi

Shell
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}'

Pour chaque domaine, nous trouvons les comptes propres de la marque sur chaque plateforme, laissons de côté les agences et les revendeurs, suivons les comptes ensemble et ajoutons les nouveaux dès qu’ils apparaissent. Pour exclure un compte, passez exclude_advertisers ou retirez-le plus tard ; il reste exclu.

Vous pouvez aussi suivre des comptes isolés avec "advertisers": ["meta:15087023444"] ; trouvez leurs identifiants avec resolve. Pour compléter une liste existante, utilisez POST /v1/watchlists/{id}/brands ou POST /v1/watchlists/{id}/advertisers.

Votre compte limite le nombre de marques suivies, toutes listes confondues, et l’intervalle minimal. Un domaine compte pour une marque, avec jusqu’à 25 comptes ; un annonceur isolé compte aussi pour une marque.

Compte Marques Intervalle minimal
Avec les crédits gratuits 3 24 h
Après le premier pack de crédits 250 6 h

La première vérification d’un annonceur sert de référence : elle enregistre les publicités en cours et n’envoie aucun événement. Nous lisons aussi une fois ses publicités terminées, dans la mesure où la bibliothèque les affiche encore, pour que son historique ne se limite pas à ce qui tourne aujourd’hui.

L’événement

JSON
{
  "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 liste les publicités que la bibliothèque de la plateforme n’affiche plus : retirées pour non-respect des règles, supprimées par l’annonceur ou au-delà de la durée de conservation de la bibliothèque. Nous vérifions une par une les publicités arrêtées des annonceurs suivis ; deux consultations vides à au moins 20 heures d’intervalle confirment un retrait. La publicité reste dans AdLib avec removed_from_library_at renseigné, et vous pouvez les lister avec GET /v1/search?source=history&advertiser=<id>&removed=true.

Chaque requête contient X-AdLib-Event, X-AdLib-Delivery (l’identifiant de l’envoi) et X-AdLib-Signature.

Vérifier la signature

X-AdLib-Signature ressemble à t=1793102400,v1=5f2c…. v1 est le HMAC-SHA256 en hexadécimal de "<t>.<raw body>" avec le secret de votre webhook (GET /v1/webhooks/secret) :

Python
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)) < tolerance

Utilisez le corps brut tel que reçu, avant de parser le JSON. Changez le secret avec POST /v1/webhooks/secret/rotate.

Tester, inspecter et renvoyer

  • POST /v1/webhooks/test envoie un webhook.ping signé vers une URL.
  • GET /v1/webhooks/deliveries liste les envois récents avec leurs codes de statut ; GET /v1/webhooks/deliveries/{id} inclut le payload.
  • POST /v1/webhooks/deliveries/{id}/redeliver remet un envoi en file d’attente.

Les envois en échec sont retentés. Répondez vite avec un 2xx et faites le traitement ensuite.

Slack, Discord et e-mail

Indiquez dans webhook_url un incoming webhook Slack (https://hooks.slack.com/...) ou un webhook Discord (https://discord.com/api/webhooks/...) : nous publions un résumé lisible avec jusqu’à cinq publicités au lieu de l’événement JSON. Aucun code nécessaire.

Pour l’e-mail, définissez "email_alerts": true à la création, ou plus tard :

Shell
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"}'

Le récapitulatif part vers l’adresse e-mail de votre compte après chaque vérification qui a trouvé quelque chose. PATCH permet aussi de renommer une liste ; "webhook_url": "" supprime le webhook.

Sans webhooks

Omettez webhook_url et interrogez plutôt GET /v1/advertisers/{id}/changes?since= à intervalle régulier. La liste de suivi enregistre quand même chaque publicité.