Webhooks
Para que serve
Um webhook avisa um sistema externo, na hora, quando algo acontece no Tesselys: um negócio muda de status, um lançamento é liquidado, uma cobrança é paga. Em vez de o seu sistema ficar consultando o Tesselys, o Tesselys chama o endereço que você cadastrou. Usos comuns: atualizar um painel de BI, disparar fluxos numa ferramenta de automação, manter um sistema próprio sincronizado.
Onde fica
Sistema › Integrações › Inscrição de Webhook, na barra lateral. A tela lista as assinaturas com a URL de destino, a quantidade de eventos, o status (Ativo/Inativo), a data da última entrega e o número de falhas.
Antes de começar
- A funcionalidade de webhooks precisa estar no plano da empresa, e o seu perfil precisa de acesso a Inscrição de Webhook (criar, editar e excluir dependem das permissões correspondentes).
- Tenha um endereço (URL) pronto para receber requisições POST, de preferência em HTTPS e acessível pela internet.
- Defina um segredo para validar as mensagens.
- Quando a verificação em duas etapas está em uso, tenha o seu código à mão: criar a assinatura, trocar a URL ou acrescentar eventos pode pedi-lo.
Criando uma assinatura
-
Clique em Novo.
-
Preencha:
Campo Para que serve Obrigatório URL de destino Endereço que vai receber os avisos, em formato de URL válida. O Tesselys envia um POST para ela a cada evento assinado Sim Segredo (HMAC) Texto que só você e o Tesselys conhecem. Quando preenchido, cada envio leva uma assinatura que permite conferir que o aviso veio do Tesselys Não (recomendado) Eventos assinados Quais acontecimentos disparam o aviso Sim, pelo menos um Cabeçalhos personalizados Pares nome/valor enviados em todo aviso (por exemplo, um token que o seu sistema exige). Linhas sem nome são ignoradas Não -
Salve. Se pedido, informe o código da verificação em duas etapas. Remover eventos ou trocar cabeçalhos não pede o código.
Eventos disponíveis
A lista aparece no campo Eventos assinados, com busca. Cada categoria também tem a opção (todos) (por exemplo, "CRM (todos)"), que assina todos os eventos daquela categoria, inclusive os que forem acrescentados no futuro.
| Categoria | Eventos |
|---|---|
| CRM | Novo negócio criado (deal.created), Negócio atualizado (deal.updated), Status do negócio alterado (deal.status_changed), Negócio inativado (deal.deleted) |
| Financeiro | Novo lançamento financeiro (financial_entry.created), Lançamento atualizado (financial_entry.updated), Lançamento liquidado (financial_entry.paid), Lançamento inativado (financial_entry.deleted) |
| Cadastros | Nova pessoa/empresa cadastrada (person.created), Cadastro atualizado (person.updated), Cadastro inativado (person.deleted) |
| Compras | Novo pedido de compra (purchase_order.created), Pedido atualizado (purchase_order.updated), Status do pedido alterado (purchase_order.status_changed) |
| Projetos | Projeto criado, atualizado ou inativado (project.created, project.updated, project.deleted); Tarefa criada, atualizada ou com status alterado (project_task.created, project_task.updated, project_task.status_changed) |
| Agendamento | Agendamento criado, atualizado ou cancelado (appointment.created, appointment.updated, appointment.canceled) |
| Protocolo (IDP) | Novo protocolo recebido (protocol.created), Status alterado (protocol.status_changed), Processamento concluído (protocol.processing.completed), Processamento falhou (protocol.processing.failed), Vinculado a um registro (protocol.linked), Desvinculado (protocol.unlinked) |
| Cobranças | Nova cobrança gerada (charge.created), Status da cobrança alterado (charge.status_changed), Cobrança paga (charge.paid) |
| Aprovações | Nova solicitação (approval_request.created), Solicitação aprovada (approval_request.approved), Solicitação rejeitada (approval_request.rejected) |
| Contratos | Contrato criado, atualizado, com status alterado, renovado, cancelado ou suspenso (contract.created, contract.updated, contract.status_changed, contract.renewed, contract.canceled, contract.suspended) |
| Timesheet | Apontamento submetido, aprovado ou rejeitado; período fechado (timesheet.submitted, timesheet.approved, timesheet.rejected, timesheet.closed) |
| Inbox (Omnichannel) | Conversa criada, resolvida ou atribuída (inbox_conversation.created, inbox_conversation.resolved, inbox_conversation.assigned); mensagem recebida ou enviada (inbox_message.received, inbox_message.sent) |
Não existem eventos separados de "ganho" e "perdido" para negócios: essas mudanças chegam em Status do negócio alterado. O mesmo vale para tarefas e pedidos de compra.
O que o seu sistema recebe
Cada aviso é um POST com corpo em JSON neste formato:
{
"event": "deal.status_changed",
"timestamp": "2026-03-25T14:30:00.000Z",
"data": { "...": "dados do registro" }
}
O conteúdo de data depende do tipo de registro do evento.
Junto vão estes cabeçalhos:
| Cabeçalho | Conteúdo |
|---|---|
X-Webhook-Event | Nome do evento (ex.: deal.status_changed) |
X-Webhook-Delivery-Id | Identificador da entrega; o mesmo em todas as tentativas daquela entrega |
X-Webhook-Timestamp | Momento do envio, em segundos (Unix) |
X-Webhook-Signature | Só quando a assinatura tem segredo: sha256= seguido do HMAC-SHA256 do corpo, em hexadecimal |
| Cabeçalhos personalizados | Os que você cadastrou na assinatura |
Validando a assinatura
- Calcule o HMAC-SHA256 do corpo recebido, exatamente como chegou, usando o segredo cadastrado.
- Compare o resultado (em hexadecimal, com o prefixo
sha256=) com o cabeçalhoX-Webhook-Signature. - Se forem iguais, o aviso é autêntico.
O segredo é definido por você no cadastro e não é exibido depois. Ao editar, deixe o campo em branco para manter o atual; digite um novo valor só se quiser trocá-lo (e atualize o seu sistema ao mesmo tempo).
Acompanhando as entregas
Abra o menu ⋮ da assinatura e escolha Ver entregas para ver o histórico. Cada entrega mostra o evento, a data e hora, o status, o código HTTP que o seu sistema respondeu, a duração, o número de tentativas e o início da resposta.
| Status | O que significa |
|---|---|
| Pendente | Na fila para envio |
| Entregue | Seu sistema respondeu com código 2xx |
| Reenviando | Falhou e há nova tentativa agendada |
| Falhou | Falhou de vez, sem nova tentativa automática |
| Abandonada | Esgotou as tentativas, ou a assinatura estava inativa na hora do envio |
Regras de envio:
| Situação | O que o Tesselys faz |
|---|---|
| Resposta 2xx | Marca como entregue e zera o contador de falhas da assinatura |
| Resposta 4xx (exceto 429) | Marca como Falhou, sem nova tentativa: o erro está no destino ou nos dados e repetir não resolve |
| Resposta 5xx, 429, erro de conexão ou sem resposta em 10 segundos | Agenda nova tentativa: depois de 1 minuto, 5 minutos, 30 minutos e 2 horas |
| Quatro novas tentativas sem sucesso | Marca como Abandonada |
| Endereço recusado por segurança (ex.: endereço de rede interna) | Marca como Falhou, sem nova tentativa |
Nas entregas com status Falhou ou Abandonada aparece o botão Reenviar, que coloca a entrega de novo na fila.
Cada falha (inclusive cada tentativa que não deu certo) soma 1 na coluna Falhas da assinatura, e uma entrega bem-sucedida zera a contagem. Ao chegar a 50 falhas seguidas, a assinatura é desativada e para de receber avisos. A tela não tem opção de reativar: corrija o destino e cadastre uma nova assinatura.
Editando e excluindo
- Editar (ícone de lápis): altera URL, segredo, eventos e cabeçalhos. Deixe o segredo em branco para manter o atual.
- Excluir (menu ⋮ ou no rodapé da visualização): a assinatura fica inativa e os avisos para aquele destino param. Entregas que ainda estavam na fila são marcadas como abandonadas.
- O filtro busca por parte da URL e mostra apenas as assinaturas ativas.
Regras importantes
| Regra | Detalhe |
|---|---|
| Limite por empresa | Até 20 assinaturas ativas. Acima disso aparece "Limite atingido. Não é possível criar mais de 20 assinaturas de webhook ativas por empresa." |
| Eventos | Só os da lista acima. Evento que não existe é recusado com "Eventos inválidos" |
| Várias assinaturas para o mesmo evento | Permitido; cada uma recebe a sua entrega |
| Tempo de resposta | O seu sistema tem 10 segundos para responder |
| Novas tentativas | Depois de 1 minuto, 5 minutos, 30 minutos e 2 horas; erros 4xx (exceto 429) não são repetidos |
| Desativação automática | Cada falha soma 1 na coluna Falhas, e uma entrega bem-sucedida zera a contagem. Com 50 falhas seguidas, a assinatura é desativada e para de receber avisos. A tela não tem opção de reativar: corrija o destino e cadastre uma nova assinatura |
| Segredo | Não é exibido depois de salvo |
| Endereços internos | Endereços de rede interna são recusados por segurança |
Boas práticas
- Responda com código 200 o mais rápido possível e processe os dados depois, em segundo plano.
- Trate avisos repetidos: numa nova tentativa, o mesmo aviso pode chegar mais de uma vez. Use o
X-Webhook-Delivery-Idpara reconhecer repetições. - Sempre cadastre um segredo e valide a assinatura.
- Confira de vez em quando a coluna Falhas e o histórico de entregas.
Perguntas frequentes
Posso ter várias assinaturas para o mesmo evento?
Sim. Cada assinatura é independente; você pode avisar vários sistemas sobre o mesmo evento, respeitando o limite de 20 assinaturas ativas por empresa.
O que acontece se o meu servidor ficar fora do ar?
O Tesselys tenta de novo depois de 1 minuto, 5 minutos, 30 minutos e 2 horas. Se nenhuma tentativa der certo, a entrega fica como Abandonada e você pode usar Reenviar no histórico de entregas quando o servidor voltar.
A minha assinatura ficou Inativa sozinha. Por quê?
Ela chegou a 50 falhas seguidas e foi desativada. Corrija o destino e cadastre uma nova assinatura.
Apareceu "Limite atingido" ao criar uma assinatura.
A empresa já tem 20 assinaturas ativas. Exclua as que não usa mais ou junte eventos numa assinatura só.
Posso testar antes de ligar no meu sistema?
Sim. Use um serviço que gera uma URL temporária para inspecionar requisições, cadastre-a como destino e provoque um evento no Tesselys.
Webhooks disparam para ações feitas pela IA ou por automações?
Sim. O aviso depende do acontecimento no registro, não de quem o fez: vale para ações feitas na tela, pela API, por automações ou quando você pede algo à IA.
A nossa equipe ajuda você a configurar e usar esse recurso.