Receber avisos do Hades no seu sistema (webhook)

O webhook é o Hades avisando o seu sistema (ERP, CRM, planilha, automação) no momento em que algo acontece, sem o seu sistema precisar ficar perguntando. Ele é do plano Oráculo pra cima, e quem cadastra é o dono ou um gestor, em Integrações.

Os avisos que existem

• Análise da reunião pronta — logo depois de cada reunião: resumo, dores, objeções, próximos passos.
• Desfecho da reunião informado — quando o vendedor diz se fechou, avançou, ficou em follow-up ou perdeu.
• Contato novo — lead de campanha, de formulário, da reunião ou criado à mão.
• Negócio mudou de etapa — toda troca de etapa no pipeline, feita por pessoa ou pelo Hades.
• Negócio ganho — quando um negócio entra em Ganhou.
• Proposta gerada — quando uma proposta nasce de uma reunião.
• Cliente respondeu o follow-up — quando o cliente responde no WhatsApp e a cadência para sozinha.

Reunião de teste nunca gera aviso, e a transcrição da conversa nunca vai no aviso (só o resumo e a análise).

Cadastrar o endereço

1. Clique na sua foto (ou nas iniciais), no pé do menu da esquerda, e escolha Integrações. Role até a seção Webhook.
2. Em Endereço que recebe os avisos, cole o endereço do seu sistema. Ele precisa começar com https:// (não aceita endereço de rede interna nem com usuário e senha).
3. Em Quais avisos mandar, deixe marcados só os que o seu sistema vai usar.
4. Clique em Cadastrar endereço.
5. Aparece o segredo: ele não aparece de novo. Clique em Copiar, guarde no seu sistema e clique em Já guardei. É com ele que o seu sistema confere que o aviso veio mesmo do Hades.
6. Clique em Enviar teste. Em até 1 minuto o aviso de teste chega no seu endereço, e a resposta do seu sistema aparece em Últimas entregas.

O que o seu sistema recebe

Cada aviso é um POST com JSON no seu endereço. O corpo traz sempre id, tipo (por exemplo reuniao.analisada), versao, criado_em, workspace_id e dados (o contato, a reunião, o negócio ou a proposta). Nos avisos de mudança também vem mudanca, com o antes e o depois (a etapa de onde saiu e pra onde foi, por exemplo). Os cabeçalhos que importam:

• X-Hades-Evento — o id do aviso. É o mesmo em toda tentativa: se o seu sistema já processou, responda 200 e ignore.
• X-Hades-Tipo — o tipo do aviso.
• X-Hades-Assinatura — a prova de que veio do Hades, no formato t=...,v1=....

Pra conferir a assinatura, calcule o HMAC SHA-256 do texto t.corpo (o t do cabeçalho, um ponto e o corpo cru, antes de qualquer JSON.parse) usando o seu segredo, e compare com o v1. Recuse se o t for mais velho que 5 minutos. Exemplo em Node:

const crypto = require("crypto");

function veioDoHades(cabecalho, corpo, segredo) {
  const p = Object.fromEntries(cabecalho.split(",").map((x) => x.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  const esperado = crypto.createHmac("sha256", segredo).update(p.t + "." + corpo).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(p.v1 || ""));
}

O que acontece se o seu sistema não responder

• Responda 2xx em até 10 segundos. O Hades não segue redirecionamento.
• Erro 5xx, 408, 429 ou sem resposta: o Hades tenta de novo em 1 min, 5 min, 30 min, 2 h, 6 h e 24 h. Depois da última, o aviso fica como esgotado.
• Outro erro 4xx: o aviso é dado como recusado e não é repetido.
• Se o endereço falha por 3 dias seguidos, o Hades desliga o endereço e avisa o dono no sino. A linha mostra Desligado: falhou por 3 dias; depois de consertar o seu sistema, clique em Ligar de novo.
• Enquanto há falha, a linha mostra Falhando desde a data em que começou.

Mexer no endereço depois

• Editar avisos — troca quais avisos chegam (clique em Salvar os avisos).
• Desligar e Ligar de novo — pausa e retoma sem perder o segredo. Desligar é sempre possível, mesmo se a empresa mudar de plano.
• Gerar segredo novo — o segredo antigo para de valer na hora; o seu sistema precisa receber o novo.
• Apagar — apaga o endereço e o histórico de entregas dele.
• Adicionar outro endereço — um sistema por endereço, cada um com o seu segredo e os seus avisos.

Prefere buscar os dados quando quiser em vez de receber avisos? Veja criar uma chave de API. Se um aviso não chega, comece pelo Últimas entregas: ali está a resposta que o seu sistema deu a cada tentativa.