Eventos e alertas de monitores: webhooks e notificações por e-mail

• 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

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

​

Tipos de evento

• 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.

• 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

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

​

Assinatura e novas tentativas

• 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.

​

Liste e reenvie eventos

​

Alertas

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

• Janela: as respostas pontuadas dos últimos 7 dias, em todos os prompts e mecanismos do monitor. O relatório 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.

​

Histórico de alertas

​

Envie um alerta de teste

​

Próximos passos