Webhooks — receber eventos

Configure em Automações → Webhooks, ou pela API (seção 22).

Configure em Automações → Webhooks, ou pela API (seção 22).

Eventos disponíveis

Cada linha abaixo é um valor válido para events na criação/edição do webhook (seção 22) e para event no disparo de teste. GET/api/webhooks/events devolve a mesma lista, ao vivo, com rótulo e categoria.

Categoria Eventos
Conversas conversation.created, conversation.updated, conversation.resolved, conversation.assigned
Mensagens message.received, message.sent, message.updated
Contatos contact.created, contact.updated, contact.deleted, contact.tag_added, contact.tag_removed
Negócios deal.created, deal.updated, deal.stage_changed, deal.deleted, deal.tag_added, deal.tag_removed, deal.won, deal.lost
Empresas company.created, company.updated, company.deleted, company.tag_added, company.tag_removed
Produtos product.created, product.updated, product.archived, product.deleted, product.stock_low
Etiquetas tag.created, tag.updated, tag.deleted
Tarefas task.created, task.updated, task.completed, task.deleted
Agenda event.created, event.updated, event.canceled
IA agent.escalated

O card "Acionar webhook" de uma automação também entrega num webhook cadastrado aqui, com a mesma assinatura e a mesma retentativa — mas ele não é um evento que se assina: quem escolhe o destino é a própria automação. Na tela de Webhooks a entrega aparece como "Acionado por uma automação".

Verificando a assinatura

Toda entrega vem assinada, para você confirmar que veio mesmo do Salos:

x-salos-signature: t=1782950400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  • t — horário Unix (segundos) em que a assinatura foi gerada
  • v1 — HMAC-SHA256, em hexadecimal, de `${t}.${corpo}`, usando o segredo do endpoint como chave
const crypto = require("node:crypto");

const TOLERANCIA_SEGUNDOS = 300; // 5 minutos — janela anti-replay

function verificarAssinaturaSalos({ header, corpoBruto, segredo }) {
  const partes = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(partes.t);
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCIA_SEGUNDOS) return false;

  const esperado = crypto.createHmac("sha256", segredo).update(`${t}.${corpoBruto}`).digest("hex");
  const recebido = Buffer.from(String(partes.v1 ?? ""), "hex");
  const querido = Buffer.from(esperado, "hex");
  if (recebido.length !== querido.length) return false;
  return crypto.timingSafeEqual(recebido, querido); // comparação em tempo constante
}

Verifique sobre o corpo BRUTO — a string exata que você recebeu, antes de qualquer JSON.parse e re-serialização. Reserializar muda espaços e ordem de chaves, e a assinatura deixa de bater.

Corpo da entrega

{
  "id": "5f2e8b1a-7c4d-4e9f-8a3b-6d1c9e5f2a84",
  "event": "deal.won",
  "created_at": "2026-07-02T12:00:00.000Z",
  "data": {
    "deal": {
      "id": "6d2c9f4e-1b7a-4e3d-8c5f-2a9b4d7e6f95",
      "name": "Plano Pro — Acme LTDA",
      "value": 12000,
      "previous_stage": "negotiation",
      "new_stage": "won",
      "owner_id": "9b1d3f7a-2e5c-4a8b-9d6f-3c7e1b4a8d52",
      "previous_column_id": "2f8a1c6d-4b9e-4d3a-8f1c-7e2b5a9d3c64",
      "new_column_id": "8c4e2a9f-6d1b-4f7c-9a3e-5b8d2c6f1a97"
    }
  }
}

id é único por entrega — use para deduplicar do seu lado, porque as retentativas reenviam o mesmo id.

Entrega e retentativa

Timeout de resposta 10 segundos
Considerado entregue qualquer status 2xx
Retentativas 6 tentativas, com esperas de 1 min, 5 min, 30 min, 2 h e 12 h
Última tentativa cerca de 14h36 depois da primeira
Desativação automática 5 entregas seguidas falhando desligam o endpoint
Método e cabeçalhos POST, com content-type: application/json, user-agent: Salos-Webhooks/1 e x-salos-signature
Redirecionamento (3xx) não é seguido — conta como falha. Cadastre o endereço final

Uma entrega conta como falha só depois de esgotar as 6 tentativas. Uma entrega bem-sucedida no meio zera a contagem — uma queda pontual do seu servidor não desliga a integração. Um servidor que cai de madrugada e volta algumas horas depois recebe a reentrega.

Quando o endpoint é desligado sozinho, a tela de Webhooks mostra o motivo (ex.: "5 entregas seguidas falharam. Último erro: HTTP 500."). Religar zera a contagem.

Enquanto o endpoint está desligado, os eventos não são entregues NEM guardados. Não existe fila acumulada esperando você religar.