Listas de seguimiento y webhooks
Añade anunciantes a una lista de seguimiento y entérate cuando sus anuncios empiezan, se detienen, cambian o desaparecen de una biblioteca, por webhook firmado, Slack, Discord o correo.
Una lista de seguimiento es una lista de marcas y anunciantes que comprobamos de forma programada. Tras cada comprobación recibes un evento por anunciante con los anuncios nuevos, detenidos, modificados y retirados. Puede llegar a tu propio endpoint (firmado), directamente a un canal de Slack o Discord, o a tu correo.
Crear una lista de seguimiento
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}'Para cada dominio buscamos las cuentas propias de la marca en todas las plataformas, dejamos fuera agencias y revendedores, seguimos las cuentas juntas y añadimos las nuevas según aparecen. Para excluir una cuenta, pásala en exclude_advertisers o quítala más tarde; no vuelve a entrar.
También puedes seguir cuentas sueltas con "advertisers": ["meta:15087023444"]; sus ids los encuentras con resolve. Para añadir a una lista existente, usa POST /v1/watchlists/{id}/brands o POST /v1/watchlists/{id}/advertisers.
Tu cuenta limita las marcas que sigues entre todas tus listas y el intervalo más corto. Un dominio es una marca, con hasta 25 cuentas; un anunciante suelto también cuenta como una marca.
| Cuenta | Marcas | Intervalo más corto |
|---|---|---|
| Con los créditos gratuitos | 3 | 24 h |
| Tras el primer pack de créditos | 250 | 6 h |
La primera comprobación de un anunciante sirve de punto de partida: registra los anuncios actuales y no envía ningún evento. También leemos una vez sus anuncios terminados, hasta donde la biblioteca todavía los muestre, para que su historial no empiece solo con lo que está activo hoy.
El evento
{
"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 recoge los anuncios que la biblioteca de la propia plataforma ya no muestra: retirados por incumplir sus políticas, borrados por el anunciante o fuera del periodo de conservación de la biblioteca. Comprobamos uno a uno los anuncios detenidos de los anunciantes en seguimiento; dos consultas vacías con al menos 20 horas de diferencia confirman una retirada. El anuncio se queda en AdLib con removed_from_library_at rellenado, y puedes listarlos con GET /v1/search?source=history&advertiser=<id>&removed=true.
Cada petición lleva X-AdLib-Event, X-AdLib-Delivery (el id del envío) y X-AdLib-Signature.
Verificar la firma
X-AdLib-Signature tiene esta forma: t=1793102400,v1=5f2c…. v1 es el HMAC-SHA256 en hexadecimal de "<t>.<raw body>" con tu secreto de webhook (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)) < toleranceUsa el cuerpo en bruto tal como llega, antes de parsear el JSON. Para rotar el secreto, usa POST /v1/webhooks/secret/rotate.
Probar, inspeccionar y reenviar
POST /v1/webhooks/testenvía unwebhook.pingfirmado a una URL.GET /v1/webhooks/deliverieslista los envíos recientes con sus códigos de estado;GET /v1/webhooks/deliveries/{id}incluye el payload.POST /v1/webhooks/deliveries/{id}/redelivervuelve a poner un envío en la cola.
Los envíos fallidos se reintentan. Responde rápido con un 2xx y haz el trabajo después.
Slack, Discord y correo
Pon en webhook_url un incoming webhook de Slack (https://hooks.slack.com/...) o un webhook de Discord (https://discord.com/api/webhooks/...) y publicaremos un resumen legible con hasta cinco anuncios en lugar del evento JSON. Sin escribir código.
Para recibirlo por correo, activa "email_alerts": true al crear la lista, o más tarde:
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"}'El resumen llega al correo de tu cuenta después de cada comprobación que encuentre algo. PATCH también sirve para renombrar una lista; "webhook_url": "" elimina el webhook.
Sin webhooks
Omite webhook_url y consulta periódicamente GET /v1/advertisers/{id}/changes?since=. La lista de seguimiento sigue registrando todos los anuncios.