Pular para o conteúdo principal

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​

  1. Clique em Novo.

  2. Preencha:

    CampoPara que serveObrigatório
    URL de destinoEndereço que vai receber os avisos, em formato de URL válida. O Tesselys envia um POST para ela a cada evento assinadoSim
    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 TesselysNão (recomendado)
    Eventos assinadosQuais acontecimentos disparam o avisoSim, pelo menos um
    Cabeçalhos personalizadosPares nome/valor enviados em todo aviso (por exemplo, um token que o seu sistema exige). Linhas sem nome são ignoradasNão
  3. 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.

CategoriaEventos
CRMNovo negócio criado (deal.created), Negócio atualizado (deal.updated), Status do negócio alterado (deal.status_changed), Negócio inativado (deal.deleted)
FinanceiroNovo lançamento financeiro (financial_entry.created), Lançamento atualizado (financial_entry.updated), Lançamento liquidado (financial_entry.paid), Lançamento inativado (financial_entry.deleted)
CadastrosNova pessoa/empresa cadastrada (person.created), Cadastro atualizado (person.updated), Cadastro inativado (person.deleted)
ComprasNovo pedido de compra (purchase_order.created), Pedido atualizado (purchase_order.updated), Status do pedido alterado (purchase_order.status_changed)
ProjetosProjeto 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)
AgendamentoAgendamento 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çasNova cobrança gerada (charge.created), Status da cobrança alterado (charge.status_changed), Cobrança paga (charge.paid)
AprovaçõesNova solicitação (approval_request.created), Solicitação aprovada (approval_request.approved), Solicitação rejeitada (approval_request.rejected)
ContratosContrato criado, atualizado, com status alterado, renovado, cancelado ou suspenso (contract.created, contract.updated, contract.status_changed, contract.renewed, contract.canceled, contract.suspended)
TimesheetApontamento 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)
informação

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çalhoConteúdo
X-Webhook-EventNome do evento (ex.: deal.status_changed)
X-Webhook-Delivery-IdIdentificador da entrega; o mesmo em todas as tentativas daquela entrega
X-Webhook-TimestampMomento do envio, em segundos (Unix)
X-Webhook-SignatureSó quando a assinatura tem segredo: sha256= seguido do HMAC-SHA256 do corpo, em hexadecimal
Cabeçalhos personalizadosOs que você cadastrou na assinatura

Validando a assinatura​

  1. Calcule o HMAC-SHA256 do corpo recebido, exatamente como chegou, usando o segredo cadastrado.
  2. Compare o resultado (em hexadecimal, com o prefixo sha256=) com o cabeçalho X-Webhook-Signature.
  3. Se forem iguais, o aviso é autêntico.
cuidado

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.

StatusO que significa
PendenteNa fila para envio
EntregueSeu sistema respondeu com código 2xx
ReenviandoFalhou e há nova tentativa agendada
FalhouFalhou de vez, sem nova tentativa automática
AbandonadaEsgotou as tentativas, ou a assinatura estava inativa na hora do envio

Regras de envio:

SituaçãoO que o Tesselys faz
Resposta 2xxMarca 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 segundosAgenda nova tentativa: depois de 1 minuto, 5 minutos, 30 minutos e 2 horas
Quatro novas tentativas sem sucessoMarca 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.

Desativação automática

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​

RegraDetalhe
Limite por empresaAté 20 assinaturas ativas. Acima disso aparece "Limite atingido. Não é possível criar mais de 20 assinaturas de webhook ativas por empresa."
EventosSó os da lista acima. Evento que não existe é recusado com "Eventos inválidos"
Várias assinaturas para o mesmo eventoPermitido; cada uma recebe a sua entrega
Tempo de respostaO seu sistema tem 10 segundos para responder
Novas tentativasDepois de 1 minuto, 5 minutos, 30 minutos e 2 horas; erros 4xx (exceto 429) não são repetidos
Desativação automáticaCada 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
SegredoNão é exibido depois de salvo
Endereços internosEndereç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-Id para 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.

Ainda com dúvida?

A nossa equipe ajuda você a configurar e usar esse recurso.