> ## 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 e alertas de monitores: webhooks e notificações por e-mail > Receba um webhook assinado quando as respostas de um monitor mudarem e um e-mail quando a sua taxa de menção cair abaixo de um limite. Um monitor pode avisar quando algo muda, para que você não precise fazer polling do relatório: * **Eventos de mudança** vão para o seu `webhookUrl` quando as respostas a um prompt mudam: sua marca aparece ou desaparece, um concorrente passa à frente ou um site é citado pela primeira vez. * **Alertas** enviam um e-mail aos administradores da sua conta quando a taxa de menção da marca nos últimos sete dias cai abaixo de `alertBelowPct`. ## Eventos de mudança Defina `webhookUrl` ao [criar](/pt/monitors.md#crie-um-monitor) ou atualizar um 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" }' ``` A URL precisa ser HTTPS em um host público. Defina-a com uma chave de API: os eventos são assinados com a chave que a definiu, então uma requisição sem chave (uma sessão do painel) retorna `400 VALIDATION_ERROR`. `webhookUrl: null` desliga os eventos e descarta o estado de eventos do monitor; ligá-los de novo parte do histórico dele. ### Tipos de evento | Evento | Enviado quando | | - | - | | `monitor.mention.started` | Sua marca está em pelo menos três das últimas cinco respostas a um prompt, depois de estar em menos. | | `monitor.mention.stopped` | Sua marca cai para duas ou menos das últimas cinco respostas a um prompt. | | `monitor.competitor.ahead` | Um concorrente está em pelo menos três das últimas cinco respostas a um prompt, e em mais delas que a sua marca. | | `monitor.source.first_cited` | Uma resposta cita um domínio que as respostas do monitor nunca citaram antes. | Os eventos de marca acompanham cada prompt separadamente em cada mecanismo e, em um monitor de grade, em cada ponto. O estado é lido das últimas cinco respostas, então `samples: 5` gera um estado completo em uma execução. * Um evento é enviado uma vez, quando o estado muda. Uma marca que continua fora das respostas envia um `monitor.mention.stopped` e nada mais até voltar. * Um prompt passa a ter estado quando reúne cinco respostas. Esse primeiro estado é a referência e não envia nada. * Um monitor de categoria não tem marca própria e envia só `monitor.source.first_cited`. Quando os eventos começam: * **Ao ligar `webhookUrl` em um monitor que já tem respostas**: o estado de cada prompt é reconstruído a partir das últimas cinco respostas dos últimos 30 dias, e todo domínio já citado conta como conhecido. Os eventos começam com a próxima resposta. * **Ao criar um monitor com `webhookUrl`, ou ligá-lo antes de existir qualquer resposta**: a primeira execução define os domínios conhecidos, e `monitor.source.first_cited` conta respostas de tarefas criadas depois que essa execução foi totalmente enviada. Os eventos de marca começam quando um prompt reúne cinco respostas. ### Payload Cada evento é um `POST` com corpo JSON. Por exemplo: ```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` | O tipo de evento. | | `id` | O id do evento, enviado também no cabeçalho `querying-webhook-id`. Deduplique por ele. | | `monitor` | O `id` e o `name` do monitor. | | `data.engine`, `data.prompt` | O mecanismo e o prompt a que a resposta pertence. | | `data.location` | `{ latitude, longitude }` do ponto da resposta, ou `null` sem localização. | | `data.taskId` | A resposta que causou o evento. Abra com [`GET /v1/monitors/{id}/answers/{taskId}`](/pt/monitors/evidence#leia-uma-resposta). | | `data.answers`, `data.mentions` | Respostas no estado (5) e quantas citaram a sua marca. Só em eventos de menção e de concorrente. | | `data.competitor`, `data.competitorMentions` | O concorrente e em quantas das respostas ele foi citado. Só em `monitor.competitor.ahead`. | | `data.domain`, `data.url`, `data.label` | O domínio citado pela primeira vez, a página citada e o rótulo dela. Só em `monitor.source.first_cited`, no lugar das contagens. | ### Assinatura e novas tentativas Os eventos são assinados e tentados de novo como os webhooks de tarefa: os mesmos três cabeçalhos `querying-webhook-*`, o mesmo esquema HMAC-SHA256 e o mesmo cronograma de novas tentativas. Verifique-os com o código de [Webhooks](/pt/concepts/webhooks.md#verificar-a-assinatura). Duas coisas mudam: * `querying-webhook-id` é o `id` do evento. Deduplique por ele. * A chave HMAC é o digest SHA-256 da chave de API que definiu `webhookUrl`, não da chave de uma tarefa. Depois de trocar a chave, envie `webhookUrl` de novo com a chave nova, e os eventos passam a ser assinados com ela. Se a chave que definiu `webhookUrl` for revogada ou expirar, os eventos param: cada um é marcado como `failed` com o motivo em `delivery.lastError`, e nada é enviado sem assinatura. ### Liste e reenvie eventos `GET /v1/monitors/{id}/events` ([referência](/pt/api-reference/monitors/list-events.md)) lista os eventos do mais novo para o mais antigo. | Parâmetro | Descrição | | - | - | | `limit` | 1–100, padrão 50. | | `type` | Um tipo de evento. | | `cursor` | O `nextCursor` da página anterior. | A resposta tem `webhookUrl`, `nextCursor` (`null` na última página) e `events`. Cada evento tem `id`, `type`, `createdAt`, `data` (como no payload) e `delivery`: | Campo | Significado | | - | - | | `delivery.status` | `pending` (aguardando a primeira tentativa ou uma nova tentativa), `delivered` ou `failed` (tentativas esgotadas, ou impossível de entregar). | | `delivery.attempts` | Tentativas feitas. | | `delivery.deliveredAt` | Quando um `2xx` foi recebido, ou `null`. | | `delivery.lastError` | A última falha, como `HTTP 500`, ou `null`. | `POST /v1/monitors/{id}/events/{eventId}/redeliver` ([referência](/pt/api-reference/monitors/redeliver-event.md)) reenvia agora um evento para o `webhookUrl` atual, com uma nova série de tentativas, e retorna o evento com o `delivery` atualizado. Eventos já entregues também podem ser reenviados. Retorna `409 WEBHOOK_NOT_SET` quando o monitor não tem `webhookUrl` e `404 NOT_FOUND` para um evento desconhecido. Os eventos ficam guardados por 30 dias. Um evento ainda em novas tentativas é guardado até elas terminarem. ## Alertas Defina `alertBelowPct` em um monitor de marca, uma porcentagem inteira de 1 a 100, para receber um e-mail quando a taxa de menção da marca cair abaixo dele: ```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 }' ``` Como o alerta é decidido: * **Janela**: as respostas pontuadas dos últimos 7 dias, em todos os prompts e mecanismos do monitor. O [relatório](/pt/monitors/reports.md) usa 30 dias por padrão, o que muda devagar demais para avisar alguém. * **Quando**: cada vez que uma execução agendada começa. A verificação lê as respostas já pontuadas, então reflete as execuções anteriores. * **Amostra mínima**: menos de 5 respostas pontuadas na janela nunca disparam. Um monitor novo, ou um cujos mecanismos estão falhando, fica em silêncio. * **Cruzamento, não estado**: o alerta dispara quando a taxa está abaixo do limite e o alerta está armado, e então se desarma. Ele se rearma quando a taxa volta a ficar igual ou acima do limite, então um monitor que continua baixo envia um e-mail, não um por execução. Mudar `alertBelowPct` o rearma. O e-mail vai para todos os administradores da conta que paga pelo monitor (para uma subconta, a conta principal). Ele informa a taxa arredondada, o limite, a janela e o número de respostas pontuadas, e tem um link para o monitor no painel. Um monitor de categoria não tem taxa de marca, então recusa `alertBelowPct` com `400 VALIDATION_ERROR`. `alertBelowPct: null` desliga o alerta. ### Histórico de alertas `GET /v1/monitors/{id}/alerts` ([referência](/pt/api-reference/monitors/get-alerts.md)) retorna `alertBelowPct`, `armed` e `deliveries`: os 20 e-mails de alerta mais recentes do monitor, incluindo os de teste. Cada envio tem `id`, `status` (`pending`, `sent` ou `failed`), `attempts`, `createdAt`, `sentAt`, `lastError` e `payload` (`monitorId`, `name`, `ratePct`, `threshold`, `windowDays`, `runs`). Os registros de envio ficam guardados por 90 dias. ### Envie um alerta de teste `POST /v1/monitors/{id}/alerts/test` ([referência](/pt/api-reference/monitors/test-alert.md)) enfileira um e-mail de teste pelo mesmo caminho de entrega de um alerta real, com "(test)" depois do nome do monitor, e retorna `data.queued: true`. Confira o resultado no histórico de alertas. Você pode enviar três e-mails de teste por monitor a cada cinco minutos; acima disso, a resposta é `429 RATE_LIMITED`. Um monitor de categoria retorna `400 VALIDATION_ERROR`. ## Próximos passos > **[Webhooks](/pt/concepts/webhooks.md)** > > Assinatura, novas tentativas e handlers seguros para todos os webhooks. > **[Fontes e respostas](/pt/monitors/evidence.md)** > > Abra a resposta por trás de um evento. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.