Webhooks (Saída)

Webhooks permitem que o SalesOS chame o seu sistema quando algo acontece (um lead é ofertado, um ranking é publicado, uma mensagem é disparada). Você nos dá uma URL HTTPS e um segredo; nós fazemos POST de um payload JSON assinado sempre que um evento assinado dispara.

Esta página cobre webhooks de saída (SalesOS → seu endpoint). Para enviar dados para dentro do SalesOS, veja Atividades e API Keys.

Configurar um webhook no Dashboard

Vá em Integrações → Webhooks → Novo Webhook e preencha o formulário.

Básico

Nome (obrigatório) — ex.: Notificar CRM.
Chave — um identificador estável (ex.: notify_crm).
Descrição — opcional.

Eventos (gatilhos)

Escolha uma Categoria e selecione os eventos que disparam este webhook — esta é a sua assinatura (veja o catálogo). Deixe vazio para um webhook que você só dispara manualmente (botão Testar) ou via workflow.

Destino

Método — POST (padrão), PUT ou PATCH.
Timeout (segundos) — quanto esperamos pelo seu 2xx (padrão 30).
URL (obrigatório) — seu endpoint. Precisa ser https:// e público (hosts internos/loopback são bloqueados).
Autenticação — escolha HMAC para assinar cada entrega e, em Configuração de Autenticação (JSON), informe o segredo:
{ "secret": "whsec_seu_segredo" }
(Outros esquemas disponíveis: Bearer, API Key, Basic, OAuth2.)

Avançado

Headers Customizados (JSON) — headers extras enviados em cada entrega.
Template do Payload (JSON com variáveis {{ }}) — molda o data do envelope a partir do contexto do evento, ex.: { "id": "{{event.id}}", "type": "{{event.type}}", "to": "{{event.to}}" }.

Os valores do template são interpolados em JSON. Use campos planos e escalares. Injetar um objeto aninhado via "{{event.data}}" pode não renderizar limpo hoje — confira sempre o Preview / envie um Teste antes.

Preview, testar e salvar

O formulário mostra um Preview ao vivo (headers + corpo). Clique em Salvar webhook e use Testar Webhook para enviar uma entrega de exemplo e confirmar que seu endpoint recebe — e verifica — o payload.

O envelope

No caminho de evento, cada entrega é um único objeto JSON:

{
  "id": "evt_2KWPBgLlAfxdpx2AI54pPJ85f4W",
  "type": "ranking.weekly.published",
  "version": "1",
  "ts": "2026-06-03T12:00:00.000Z",
  "tenant": "9b1f0c2e-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
  "data": { /* específico do evento — veja o catálogo */ }
}

Campo	Descrição
`id`	Id único do evento, estável entre retentativas → sua chave de idempotência.
`type`	Tipo do evento (veja o catálogo).
`version`	Versão do schema de `data`. Evolui de forma aditiva.
`ts`	Quando o evento ocorreu (ISO 8601, UTC).
`tenant`	Tenant de origem (uuid).
`data`	Payload específico do evento.

Headers

Header	Descrição
`X-SalesOS-Event`	Tipo do evento — roteie sem ler o corpo.
`X-SalesOS-Event-Id`	Igual ao `id`; estável entre retentativas (idempotência).
`X-SalesOS-Delivery-Id`	Id da tentativa (muda a cada retry; para debug).
`X-SalesOS-Timestamp`	Unix em segundos — parte da assinatura (anti-replay).
`X-SalesOS-Tenant`	Id do tenant de origem.
`X-SalesOS-Signature`	`sha256=<hmac>` — veja Verificar.

Verificar a assinatura

Sempre verifique a assinatura antes de confiar numa entrega. Sem ela, qualquer um que descobrir sua URL poderia forjar eventos.

No caminho de evento, a assinatura cobre {id}.{timestamp}.{rawBody} (padrão Standard Webhooks), então autentica o payload e o timestamp (anti-replay). Recompute o HMAC com o seu segredo, compare em tempo constante e rejeite se o timestamp estiver mais de 300s fora.

import crypto from "node:crypto";

// raw = o corpo cru exato da requisição (NÃO faça JSON.parse antes)
export function verify(req, secret) {
  const id  = req.headers["x-salesos-event-id"];
  const ts  = req.headers["x-salesos-timestamp"];
  const sig = req.headers["x-salesos-signature"]; // "sha256=<hex>"
  const raw = req.rawBody;

  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // janela de replay

  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(`${id}.${ts}.${raw}`).digest("hex");

  const a = Buffer.from(sig), b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hmac, hashlib, time

def verify(headers, raw_body: bytes, secret: str) -> bool:
    event_id = headers["X-SalesOS-Event-Id"]
    ts       = headers["X-SalesOS-Timestamp"]
    sig      = headers["X-SalesOS-Signature"]  # "sha256=<hex>"

    if abs(time.time() - int(ts)) > 300:        # janela de replay
        return False

    msg = f"{event_id}.{ts}.{raw_body.decode()}".encode()
    expected = "sha256=" + hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

Entregas de teste (o botão “Testar Webhook”) e gatilhos legados de workflow usam hoje um esquema mais simples: o corpo é o template renderizado cru (não o envelope) e o header de assinatura é X-Signature: <prefixo><hmac(corpo)> — sem o prefixo id.timestamp., então sem anti-replay. Prefira o caminho de evento acima em produção.

Catálogo de eventos

`type`	Quando dispara	`data`
`lead.offer_created`	Um lead é ofertado a um corretor	payload do lead/oportunidade
`lead.accepted`	Um corretor aceita um lead	payload do lead/oportunidade
`lead.offer_expired`	Uma oferta expira sem aceite	payload do lead/oportunidade
`mission.completed`	Uma missão é concluída	payload da missão
`ranking.weekly.published`	Ranking semanal publicado (agendado)	leaderboard (linhas por email)
`ranking.consolidated.published`	Ranking consolidado publicado	leaderboard (linhas por email)
`message.dispatch`	Mensagem disparada a um usuário/grupo	`{ to, m }`
`notification.push.dispatch`	Push disparado a um usuário/grupo	`{ to, n }`

Exemplo de data para ranking.weekly.published:

{
  "p": { "type": "weekly", "label": "Semana 23/2026", "start": "2026-05-25", "end": "2026-05-31" },
  "org_unit": null,
  "totals": { "users": 843, "points": 1820400, "missions": 5120 },
  "rows": [
    { "rank": 1, "delta": 2, "email": "maria@loja.com", "points": 4820, "missions": 37, "org_unit": "ou_12" }
  ]
}

Os destinatários são chaveados por email — nomes e ids não são enviados; enriqueça do seu lado se precisar.

Confiabilidade

Responda rápido. Retorne um status 2xx rapidamente (antes de processamento pesado) para confirmar o recebimento.

Sua resposta	O que o SalesOS faz
`2xx`	Marca a entrega como concluída. Sem retry.
`4xx` (400, 401, 422…)	Tratado como rejeição permanente. Sem retry (exceto `429`, que respeita o backoff).
`5xx` / timeout / erro de conexão	Reentrega com backoff exponencial (`2^n` minutos, até 5 tentativas), depois dead-letter.

Idempotência. O mesmo evento pode ser entregue mais de uma vez (retentativas). Deduplique por X-SalesOS-Event-Id — ele permanece o mesmo entre retentativas.

Entregas falhas aparecem no painel Entregas (Dashboard → Integrações → Webhooks), onde você inspeciona status, tentativas e o último erro, e pode reenviar a partir da fila de dead-letter.

​Webhooks (Saída)

​Configurar um webhook no Dashboard

​O envelope

​Headers

​Verificar a assinatura

​Catálogo de eventos

​Confiabilidade

Webhooks (Saída)

Configurar um webhook no Dashboard

O envelope

Headers

Verificar a assinatura

Catálogo de eventos

Confiabilidade