Saltar para o conteúdo principal

Webhooks

Webhooks permitem que sistemas externos recebam notificações em tempo real quando eventos acontecem no SalesOS.

Como funcionam

Quando um evento ocorre (ex: lead criado, deal ganho), o SalesOS envia uma requisição HTTP POST para a URL configurada, contendo os dados do evento em formato JSON.

Eventos disponíveis

EventoDescrição
lead.createdNovo lead criado
lead.updatedLead atualizado
lead.status_changedStatus do lead alterado
lead.assignedLead atribuído a um vendedor
deal.createdNova oportunidade criada
deal.stage_changedOportunidade mudou de etapa
deal.wonDeal marcado como ganho
deal.lostDeal marcado como perdido
deal.updatedOportunidade atualizada
activity.createdNova atividade registrada

Configurando webhooks

Via interface

1

Acesse a configuração

Vá em Configurações > Integrações > Webhooks.
2

Adicione um webhook

Clique em Novo webhook e preencha:
  • URL — Endpoint que receberá os eventos
  • Eventos — Selecione quais eventos disparam o webhook
  • Secret — Chave para validação de assinatura (gerada automaticamente)
3

Teste o webhook

Clique em Enviar teste para verificar se o endpoint está recebendo corretamente.
4

Ative

Ative o webhook para começar a receber eventos reais.

Via API

POST /v1/webhooks
{
  "url": "https://seu-sistema.com/webhooks/salesos",
  "events": ["lead.created", "deal.won", "deal.lost"],
  "secret": "sua_chave_secreta"
}

Formato do payload

{
  "id": "evt_uuid",
  "event": "deal.won",
  "timestamp": "2026-03-15T14:30:00Z",
  "data": {
    "id": "uuid",
    "name": "Projeto ABC",
    "value": 75000.00,
    "stage": "closed_won",
    "assigned_to": "uuid",
    "company": "Empresa XYZ"
  }
}

Verificação de assinatura

Cada requisição inclui o header X-SalesOS-Signature com uma assinatura HMAC-SHA256 do payload usando o secret configurado:
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
Sempre valide a assinatura do webhook antes de processar o payload para garantir que a requisição veio do SalesOS.

Retentativas

Se o endpoint retornar um erro (status >= 400) ou não responder em 10 segundos, o SalesOS faz retentativas:
TentativaIntervalo
1a retentativa1 minuto
2a retentativa5 minutos
3a retentativa30 minutos
4a retentativa2 horas
5a retentativa24 horas
Após 5 retentativas sem sucesso, o webhook é desativado automaticamente e o administrador é notificado.
Responda com status 200 o mais rápido possível. Processe o payload de forma assíncrona para evitar timeouts.

Logs de webhook

Acesse Configurações > Webhooks > Logs para visualizar:
  • Histórico de entregas
  • Status de cada requisição (sucesso ou falha)
  • Payload enviado
  • Resposta recebida
  • Tempo de resposta

Próximos passos