Enviar alertas para um webhook

Além de e-mail e Slack, um alerta pode chamar um endereço do seu próprio sistema. É por aí que você abre um chamado automaticamente, grava o evento no seu banco ou dispara um fluxo no Zapier, Make ou n8n — nenhuma dessas ferramentas exige integração dedicada: todas aceitam receber um webhook.

Como configurar

1. Vá em Alertas e crie um alerta novo (ou edite um existente).

2. Preencha nome, condição e a pesquisa, como em qualquer alerta.

3. Em Métodos de Notificação, marque Webhook.

4. Informe a URL do endpoint que vai receber a chamada e salve.

5. Depois de salvar, uma chave de assinatura aparece no formulário. Copie e guarde — é com ela que o seu sistema confirma que a chamada veio de nós.

Requisitos da URL

• Precisa usar HTTPS. Em HTTP o conteúdo e a assinatura viajariam abertos.

• Precisa ser acessível pela internet. Endereços internos (localhost, 192.168.x.x, 10.x.x.x) são recusados por segurança.

• Não pode responder com redirecionamento — a entrega é feita para o endereço informado, e só para ele.

O que enviamos

Um POST com Content-Type: application/json e um corpo neste formato:

{
  "event": "alert.triggered",
  "alert": {
    "id": "12",
    "name": "NPS crítico",
    "condition": "nps_below",
    "threshold": 30
  },
  "survey": {
    "id": "01jabc...",
    "title": "Pós-atendimento"
  },
  "context": {
    "current_nps": "12",
    "threshold": "30",
    "window": "últimos 30 dias",
    "responses": "48"
  },
  "triggered_at": "2026-07-27T12:34:56-03:00"
}

Dois detalhes importantes para quem vai programar:

• condition é um código estável, não um texto traduzido. Os valores possíveis são nps_below, nps_above, sentiment_negative, no_response, response_rate_below e new_feedback. Pode usá-los num switch sem medo de o idioma do painel mudar o comportamento.

• survey vem como null quando o alerta vale para todas as pesquisas.

Verificando a assinatura

Toda chamada leva o cabeçalho Signature, que é o HMAC-SHA256 do corpo usando a sua chave de assinatura. Confira antes de agir sobre o conteúdo — sem isso, qualquer pessoa que descubra a sua URL pode forjar um alerta. Em PHP:

$esperado = hash_hmac('sha256', $corpoBruto, $suaChave);

if (! hash_equals($esperado, $request->header('Signature'))) {
    abort(403);
}

Novas tentativas

Se o seu endpoint não responder com sucesso, tentamos novamente até 3 vezes, com espera crescente entre elas. Cada chamada tem 5 segundos de limite — responda rápido (um 200 imediato) e processe depois, em segundo plano.

Se as três tentativas falharem, o card do alerta passa a mostrar última entrega falhou com o motivo. Vale conferir essa marca de vez em quando: é como você descobre que a integração parou.

Sobre privacidade

O payload não identifica quem respondeu. Quando a pesquisa é anônima, isso é uma promessa feita ao respondente — e ela vale também aqui: o comentário e a nota vão, o nome e o e-mail não.

Trocando a URL ou removendo

Trocar o endereço mantém a mesma chave de assinatura, então você não precisa reconfigurar a verificação do outro lado. Já desmarcar o método Webhook remove a URL e apaga a chave — se voltar a ativá-lo depois, uma chave nova será gerada.