Saltar al contenido principal
Un monitor puede avisarte cuando algo se mueve, para que no tengas que consultar su informe:
  • Los eventos de cambio llegan a tu webhookUrl cuando cambian las respuestas a un prompt: tu marca aparece o desaparece, un competidor se adelanta o un sitio se cita por primera vez.
  • Las alertas envían un correo a los administradores de tu cuenta cuando la tasa de mención de la marca en los últimos siete días cae por debajo de alertBelowPct.

​
Eventos de cambio

Define webhookUrl al crear o actualizar un monitor:
La URL debe ser HTTPS en un host público. Defínela con una clave de API: los eventos se firman con la clave que la definió, así que una petición sin clave (una sesión del panel) devuelve 400 VALIDATION_ERROR. webhookUrl: null desactiva los eventos y descarta el estado de eventos del monitor; al volver a activarlos se parte de su historial.

​
Tipos de evento

Los eventos de marca siguen cada prompt por separado en cada motor y, en un monitor con cuadrícula, en cada punto. El estado se lee de las últimas cinco respuestas, así que samples: 5 da un estado completo en una sola ejecución.
  • Un evento se envía una vez, cuando cambia el estado. Una marca que sigue fuera de las respuestas envía un monitor.mention.stopped y nada más hasta que vuelve.
  • Un prompt tiene estado cuando acumula cinco respuestas. Ese primer estado es la línea base y no envía nada.
  • Un monitor de categoría no tiene marca propia y solo envía monitor.source.first_cited.
Cuándo empiezan los eventos:
  • Al activar webhookUrl en un monitor que ya tiene respuestas: el estado de cada prompt se reconstruye con sus últimas cinco respuestas de los últimos 30 días, y cada dominio ya citado cuenta como conocido. Los eventos empiezan con la siguiente respuesta.
  • Al crear un monitor con webhookUrl, o activarlo antes de que haya respuestas: la primera ejecución fija los dominios conocidos, y monitor.source.first_cited cuenta las respuestas de tareas creadas después de que esa ejecución se haya enviado por completo. Los eventos de marca empiezan cuando un prompt tiene cinco respuestas.

​
Payload

Cada evento es un POST con un cuerpo JSON. Por ejemplo:

​
Firma y reintentos

Los eventos se firman y reintentan como los webhooks de tareas: las mismas tres cabeceras querying-webhook-*, el mismo esquema HMAC-SHA256 y el mismo calendario de reintentos. Verifícalos con el código de Webhooks. Hay dos diferencias:
  • querying-webhook-id es el id del evento. Deduplica por él.
  • La clave HMAC es el digest SHA-256 de la clave de API que definió webhookUrl, no de la clave de una tarea.
Tras rotar la clave, envía webhookUrl de nuevo con la clave nueva y los eventos se firman con ella. Si la clave que definió webhookUrl se revoca o caduca, los eventos se detienen: cada uno se marca como failed con el motivo en delivery.lastError, y nunca se envía nada sin firmar.

​
Lista y reenvía eventos

GET /v1/monitors/{id}/events (referencia) lista los eventos del más nuevo al más antiguo. La respuesta tiene webhookUrl, nextCursor (null en la última página) y events. Cada evento tiene id, type, createdAt, data (como en el payload) y delivery: POST /v1/monitors/{id}/events/{eventId}/redeliver (referencia) vuelve a enviar un evento ahora a la webhookUrl actual, con una nueva tanda de reintentos, y devuelve el evento con su delivery actualizado. También se pueden reenviar eventos ya entregados. Devuelve 409 WEBHOOK_NOT_SET cuando el monitor no tiene webhookUrl y 404 NOT_FOUND para un evento desconocido. Los eventos se conservan 30 días. Un evento que sigue reintentándose se conserva hasta que terminan sus reintentos.

​
Alertas

Define alertBelowPct en un monitor de marca, un porcentaje entero de 1 a 100, para recibir un correo cuando la tasa de mención de la marca caiga por debajo:
Cómo se decide la alerta:
  • Ventana: las respuestas puntuadas de los últimos 7 días, en todos los prompts y motores del monitor. El informe usa 30 días por defecto, que se mueve demasiado despacio para avisar a nadie.
  • Cuándo: cada vez que empieza una ejecución programada. La comprobación lee las respuestas ya puntuadas, así que refleja las ejecuciones anteriores.
  • Muestra mínima: con menos de 5 respuestas puntuadas en la ventana nunca salta. Un monitor nuevo, o uno cuyos motores están fallando, permanece en silencio.
  • Cruce, no estado: la alerta salta cuando la tasa está por debajo del umbral y la alerta está armada, y luego se desarma. Se vuelve a armar cuando la tasa regresa al umbral o lo supera, así que un monitor que sigue bajo envía un correo una vez, no en cada ejecución. Cambiar alertBelowPct la vuelve a armar.
El correo llega a todos los administradores de la cuenta que paga el monitor (en una subcuenta, su cuenta principal). Indica la tasa redondeada, el umbral, la ventana y el número de respuestas puntuadas, y enlaza al monitor en el panel. Un monitor de categoría no tiene tasa de marca, así que rechaza alertBelowPct con 400 VALIDATION_ERROR. alertBelowPct: null desactiva la alerta.

​
Historial de alertas

GET /v1/monitors/{id}/alerts (referencia) devuelve alertBelowPct, armed y deliveries: los 20 correos de alerta más recientes del monitor, pruebas incluidas. Cada envío tiene id, status (pending, sent o failed), attempts, createdAt, sentAt, lastError y payload (monitorId, name, ratePct, threshold, windowDays, runs). Los registros de envío se conservan 90 días.

​
Envía una alerta de prueba

POST /v1/monitors/{id}/alerts/test (referencia) pone en cola un correo de prueba por la misma vía de envío que una alerta real, con «(test)» tras el nombre del monitor, y devuelve data.queued: true. Comprueba el resultado en el historial de alertas. Puedes enviar tres correos de prueba por monitor cada cinco minutos; más devuelve 429 RATE_LIMITED. Un monitor de categoría devuelve 400 VALIDATION_ERROR.

​
Próximos pasos

Webhooks

Firma, reintentos y handlers seguros para todos los webhooks.

Fuentes y respuestas

Abre la respuesta que hay detrás de un evento.