> ## Documentation Index > Fetch the complete documentation index at: https://docs.querying.ai/llms.txt > Use this file to discover all available pages before exploring further. # Eventos y alertas de monitores: webhooks y notificaciones por correo > Recibe un webhook firmado cuando cambian las respuestas de un monitor y un correo cuando tu tasa de mención cae por debajo de un umbral. 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](/es/monitors.md#crea-un-monitor) o actualizar un monitor: ```bash theme={"theme":"css-variables"} curl -X PATCH https://api.querying.ai/v1/monitors/$MONITOR_ID \ -H "Authorization: Bearer $QUERYING_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "webhookUrl": "https://hooks.example.com/querying/monitors" }' ``` 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 | Evento | Se envía cuando | | - | - | | `monitor.mention.started` | Tu marca está en al menos tres de las últimas cinco respuestas a un prompt, tras haber estado en menos. | | `monitor.mention.stopped` | Tu marca baja a dos o menos de las últimas cinco respuestas a un prompt. | | `monitor.competitor.ahead` | Un competidor está en al menos tres de las últimas cinco respuestas a un prompt, y en más que tu marca. | | `monitor.source.first_cited` | Una respuesta cita un dominio que las respuestas del monitor nunca habían citado. | 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: ```json theme={"theme":"css-variables"} { "event": "monitor.mention.stopped", "id": "fd61d8f6-ebdf-4162-8b55-fd052c8502a9", "createdAt": "2026-10-10T03:12:44.120Z", "monitor": { "id": "d39b8de0-b159-4229-bf58-7064e5369db1", "name": "Earbud brand tracking" }, "data": { "engine": "CHATGPT", "prompt": "best wireless earbuds for commuting", "location": null, "taskId": "863edb44-fc62-40dd-a5be-2af9409d59b6", "answers": 5, "mentions": 2 } } ``` | Campo | Significado | | - | - | | `event` | El tipo de evento. | | `id` | El id del evento, que también se envía en la cabecera `querying-webhook-id`. Deduplica por él. | | `monitor` | El `id` y el `name` del monitor. | | `data.engine`, `data.prompt` | El motor y el prompt de la respuesta. | | `data.location` | `{ latitude, longitude }` del punto de la respuesta, o `null` sin ubicación. | | `data.taskId` | La respuesta que causó el evento. Ábrela con [`GET /v1/monitors/{id}/answers/{taskId}`](/es/monitors/evidence#lee-una-respuesta). | | `data.answers`, `data.mentions` | Respuestas del estado (5) y cuántas nombraron tu marca. Solo eventos de mención y de competidor. | | `data.competitor`, `data.competitorMentions` | El competidor y cuántas de las respuestas lo nombraron. Solo `monitor.competitor.ahead`. | | `data.domain`, `data.url`, `data.label` | El dominio citado por primera vez, la página citada y su etiqueta. Solo `monitor.source.first_cited`, en lugar de los recuentos. | ### 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](/es/concepts/webhooks.md#verifica-la-firma). 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](/es/api-reference/monitors/list-events.md)) lista los eventos del más nuevo al más antiguo. | Parámetro | Descripción | | - | - | | `limit` | De 1 a 100, por defecto 50. | | `type` | Un tipo de evento. | | `cursor` | El `nextCursor` de la página anterior. | 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`: | Campo | Significado | | - | - | | `delivery.status` | `pending` (esperando un primer intento o un reintento), `delivered` o `failed` (reintentos agotados, o no entregable). | | `delivery.attempts` | Intentos realizados. | | `delivery.deliveredAt` | Cuándo se recibió un `2xx`, o `null`. | | `delivery.lastError` | El último fallo, como `HTTP 500`, o `null`. | `POST /v1/monitors/{id}/events/{eventId}/redeliver` ([referencia](/es/api-reference/monitors/redeliver-event.md)) 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: ```bash theme={"theme":"css-variables"} curl -X PATCH https://api.querying.ai/v1/monitors/$MONITOR_ID \ -H "Authorization: Bearer $QUERYING_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "alertBelowPct": 40 }' ``` 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](/es/monitors/reports.md) 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](/es/api-reference/monitors/get-alerts.md)) 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](/es/api-reference/monitors/test-alert.md)) 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](/es/concepts/webhooks.md)** > > Firma, reintentos y handlers seguros para todos los webhooks. > **[Fuentes y respuestas](/es/monitors/evidence.md)** > > Abre la respuesta que hay detrás de un evento. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.