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

Os eventos sao organizados por categoria (CRM, Financeiro, Projetos, Compras, Contratos, Agendamento, Cobrancas, Inbox, Aprovacoes, Timesheet, Protocolo). Alguns dos principais:

Evento	Descricao
deal.created / deal.updated / deal.status_changed / deal.deleted	Negocio criado, atualizado, mudou de status (inclui ganho/perdido) ou removido
person.created / person.updated / person.deleted	Pessoa criada, atualizada ou removida
financial_entry.created / financial_entry.updated / financial_entry.paid / financial_entry.deleted	Lancamento financeiro criado, atualizado, baixado (pago) ou removido
project.created / project.updated / project.deleted	Projeto criado, atualizado ou removido
project_task.created / project_task.updated / project_task.status_changed	Tarefa de projeto criada, atualizada ou com mudanca de status (ex.: concluida)
purchase_order.created / purchase_order.updated / purchase_order.status_changed	Ordem de compra criada, atualizada ou com mudanca de status (ex.: aprovada)
contract.created / contract.status_changed / contract.renewed / contract.canceled	Contrato criado, com mudanca de status, renovado ou cancelado
charge.created / charge.paid / charge.status_changed	Cobranca criada, paga ou com mudanca de status
appointment.created / appointment.updated / appointment.canceled	Compromisso criado, atualizado ou cancelado
approval_request.created / approval_request.approved / approval_request.rejected	Solicitacao de aprovacao criada, aprovada ou rejeitada
timesheet.submitted / timesheet.approved / timesheet.rejected / timesheet.closed	Apontamento de horas enviado, aprovado, rejeitado ou fechado

informação

Nao existem eventos separados de "ganho" e "perdido" para negocios — essas transicoes chegam em deal.status_changed. O mesmo vale para tarefas (use project_task.status_changed) e ordens de compra (purchase_order.status_changed). A lista completa e atualizada de eventos por categoria fica disponivel na tela de criacao da inscricao e na Referencia de API.

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.