Docs

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

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

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

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 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):

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

Usa 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/test envía un webhook.ping firmado a una URL.
  • GET /v1/webhooks/deliveries lista los envíos recientes con sus códigos de estado; GET /v1/webhooks/deliveries/{id} incluye el payload.
  • POST /v1/webhooks/deliveries/{id}/redeliver vuelve 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:

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

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.