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=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdt— horário Unix (segundos) em que a assinatura foi geradav1— 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.parsee 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.