Como configurar webhooks de saída

Permite Slack, Monday, sistema interno seu, etc., receberem eventos do Lefia em tempo real.

Configurar

No detalhe da empresa (/admin/empresa/[id]), seção Webhooks:

1. + Novo webhook
2. Preenche:

- Nome (ex: "Slack #integracoes")
- URL (HTTPS obrigatório)
- Eventos (toggle): message.received, message.sent, message.error, integration.test_success, integration.test_failure

1. Clica Criar

Secret

No momento da criação, o secret é mostrado uma única vez — copie e guarde. É usado pra você verificar autenticidade dos webhooks via header X-Lefia-Signature: sha256=<hmac> (o header legado X-Nexio-Signature segue sendo enviado em paralelo, com o mesmo valor, para integrações que ainda o verificam).

Verificação HMAC (Node.js exemplo)

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, body, signatureHeader) {
  const expected = createHmac("sha256", secret).update(body).digest("hex");
  const got = signatureHeader.replace(/^sha256=/, "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(got));
}

Painel

Lista mostra: deliveries, falhas, taxa de erro, última entrega, último erro inline.

Destino webhook: assinar o corpo (HMAC)

Na conexão de destino com protocolo Webhook (assistente, criação manual ou Editar), o campo Assinar o corpo define se o Lefia assina o que entrega. O padrão é Não assinar.

• Lefia v2 (recomendado): envia X-Lefia-Timestamp (segundos Unix) e X-Lefia-Signature-V2 = sha256= + HMAC-SHA256 do texto carimbo.corpo com o segredo. O receptor deve recusar carimbo com mais de 5 minutos (proteção contra reenvio). É o que o webhook de entrada do próprio Lefia exige.
• Legado: envia X-Hub-Signature-256 e X-Webhook-Signature = sha256= + HMAC-SHA256 do corpo. Sem carimbo, pode ser reenviado: use só quando o parceiro pedir.

O Segredo da assinatura pode ser colado (o que o receptor forneceu) ou gerado com Gerar (whsec_…, 32 bytes aleatórios). Copie antes de salvar: depois o segredo fica oculto e só pode ser substituído. Assinatura ligada sem segredo = o envio não sai (erro na mensagem).

O Testar conexão manda um ping sem assinatura, de propósito (assinado, o receptor o aceitaria como documento). Com a assinatura ligada, uma resposta 401/403 do receptor conta como alcançável. Os Headers customizados da conexão são enviados em todo POST, mas não substituem os cabeçalhos da assinatura.