Webhooks

Webhooks permitem que sistemas externos recebam notificacoes automaticas quando eventos acontecem no Tesselys. Em vez de consultar a API periodicamente, seu sistema e avisado em tempo real.

Conceito

Um webhook e uma URL do seu sistema que o Tesselys chama automaticamente quando um evento ocorre. Por exemplo, quando um deal e ganho, o Tesselys envia um POST para a URL configurada com os dados do deal.

Isso permite integracoes em tempo real com:

• Sistemas de BI e dashboards
• Sistemas externos
• Ferramentas de automacao (Zapier, Make, n8n)
• Sistemas proprios da sua empresa

Criando uma inscricao de webhook

Acesse Configuracoes > Webhooks e clique em Nova Inscricao. Preencha:

Campo	Descricao	Obrigatorio
Nome	Nome descritivo (ex: "Notificar BI sobre deals")	Sim
URL	Endereco que recebera as notificacoes (HTTPS)	Sim
Eventos	Quais eventos devem disparar a notificacao	Sim
Ativo	Se a inscricao esta ativa ou pausada	Sim

dica

Use HTTPS obrigatoriamente. Webhooks enviados para URLs HTTP nao sao suportados por questoes de seguranca.

Eventos disponiveis

Evento	Descricao
deal.created	Deal criado
deal.updated	Deal atualizado
deal.won	Deal marcado como ganho
deal.lost	Deal marcado como perdido
person.created	Pessoa criada
person.updated	Pessoa atualizada
financial_entry.created	Lancamento financeiro criado
task.completed	Tarefa concluida
project.created	Projeto criado
ticket.created	Ticket de suporte criado

Voce pode selecionar multiplos eventos por inscricao.

Formato do payload

Quando um evento ocorre, o Tesselys envia um POST HTTP para a URL configurada com o seguinte formato:

{
  "event": "deal.won",
  "timestamp": "2026-03-25T14:30:00Z",
  "data": {
    "id": "abc-123",
    "title": "Projeto Website",
    "amount": 50000,
    "status": "WON"
  }
}

O campo data contem os dados da entidade relacionada ao evento. A estrutura varia conforme o tipo de entidade.

Seguranca (validacao de assinatura)

Cada webhook enviado inclui um header X-Webhook-Signature com uma assinatura HMAC-SHA256. Para validar:

1. Ao criar a inscricao, voce recebe um secret unico.
2. Quando receber um webhook, calcule o HMAC-SHA256 do body usando o secret.
3. Compare o resultado com o valor do header X-Webhook-Signature.
4. Se forem iguais, o webhook e autentico.

cuidado

Sempre valide a assinatura antes de processar o webhook. Isso garante que a notificacao realmente veio do Tesselys e nao de um terceiro mal-intencionado.

Logs de entrega

Na tela da inscricao, voce encontra o historico de entregas:

Informacao	Descricao
Data/hora	Quando o webhook foi enviado
Evento	Qual evento disparou
Status HTTP	Codigo de resposta do seu servidor
Tentativa	Numero da tentativa (em caso de retry)

Retentativas (retry)

Se o seu servidor nao responder com status 2xx, o Tesselys tenta novamente:

• 1a retentativa: apos 1 minuto
• 2a retentativa: apos 5 minutos
• 3a retentativa: apos 30 minutos

Apos 3 falhas consecutivas, o webhook e marcado como falho no log. A inscricao continua ativa para os proximos eventos.

Boas praticas

• Responda com status 200 o mais rapido possivel. Processe os dados de forma assincrona.
• Implemente idempotencia: o mesmo webhook pode ser entregue mais de uma vez em caso de timeout.
• Monitore os logs de entrega regularmente para identificar falhas.
• Use o secret de assinatura para validar todos os webhooks recebidos.

Perguntas frequentes

Posso ter varias inscricoes para o mesmo evento?

Sim. Cada inscricao e independente. Voce pode notificar varios sistemas sobre o mesmo evento.

O que acontece se meu servidor ficar fora do ar?

O Tesselys tenta reenviar ate 3 vezes. Se todas as tentativas falharem, o evento e registrado no log como falho. Voce pode consultar o log para reprocessar manualmente.

Posso testar webhooks antes de ativar?

Sim. Use servicos como webhook.site ou RequestBin para criar uma URL temporaria e testar o recebimento dos payloads.

Webhooks funcionam para acoes feitas via IA?

Sim. Qualquer acao na plataforma dispara os webhooks configurados, independentemente de ter sido feita manualmente, via API ou via comandos de IA.