Pular para o conteúdo principal

Configuração de webhooks

Com um webhook, o Tesselys avisa o seu sistema quando algo acontece (um negócio muda de status, um lançamento é liquidado, uma cobrança é paga), com uma requisição POST para a URL que você cadastrar. Assim você não precisa consultar a API de tempos em tempos.

Cadastrando uma assinatura​

As assinaturas são cadastradas na tela do Tesselys. Não há rota da API Externa para isso.

  1. No menu lateral, seção Sistema, entre em Integrações > Inscrição de Webhook.
  2. Clique em Novo e preencha:
CampoPara que serveObrigatório
URL de destinoEndereço que recebe os avisos por POST. Use HTTPS.Sim
Segredo (HMAC)Texto que só você e o Tesselys conhecem. Com ele, cada aviso leva a assinatura X-Webhook-Signature (veja Validação da assinatura).Não, mas recomendado
Eventos assinadosQuais eventos disparam o aviso. Cada categoria tem a opção "(todos)", que assina os eventos daquela categoria, inclusive os que forem criados depois.Sim
Cabeçalhos personalizadosPares nome/valor enviados em todo aviso (por exemplo, um token que o seu sistema exige).Não
  1. Salve.

Regras:

  • Até 20 assinaturas ativas por empresa.
  • Só são aceitos os eventos da lista de eventos; um evento desconhecido é recusado no cadastro.
  • O segredo é definido por você e não volta a ser exibido. Na edição, deixe o campo em branco para manter o atual.
  • Criar uma assinatura, trocar a URL ou acrescentar eventos são ações sensíveis: quem usa verificação em duas etapas pode ter de confirmar com o código.
  • Ver e gerenciar a tela exige o recurso Webhooks e Integrações no plano e permissão no perfil de acesso.

O que o seu sistema recebe​

POST /seu-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Ideros-ERP-Webhook/1.0
X-Webhook-Event: deal.status_changed
X-Webhook-Delivery-Id: 4f1c2a9b7e3d4c5a8b6f0e1d
X-Webhook-Timestamp: 1763389800
X-Webhook-Signature: sha256=5d2c0f…
{
"event": "deal.status_changed",
"timestamp": "2026-11-17T14:30:00.000Z",
"data": {
"id": "6a1f3c9e8b2d4f0a1c3e5b7d",
"companyId": "…",
"title": "Licença anual — Tech Solutions",
"previousStatus": "APPROVED",
"newStatus": "WINNER"
}
}
CabeçalhoConteúdo
X-Webhook-EventNome do evento.
X-Webhook-Delivery-IdIdentificador da entrega. É o mesmo em todas as tentativas da mesma entrega: use-o para não processar o mesmo aviso duas vezes.
X-Webhook-TimestampMomento do envio desta tentativa, 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.

O corpo tem sempre event, timestamp (momento em que o evento aconteceu) e data. O conteúdo de data muda de evento para evento e traz os dados principais do registro, não o registro inteiro: use o id para buscar o resto pela API, se precisar. Veja os campos de cada evento em Eventos.

Entregas e novas tentativas​

O seu sistema respondeO que o Tesselys faz
2xx em até 10 segundosMarca como entregue e zera o contador de falhas da assinatura.
4xx (exceto 429)Marca como falhou, sem nova tentativa: o erro está no destino e repetir não resolve.
5xx, 429, erro de conexão ou nada em 10 segundosAgenda nova tentativa: depois de 1 minuto, 5 minutos, 30 minutos e 2 horas.
Quatro novas tentativas sem sucessoMarca como abandonada.
URL que aponta para endereço interno ou privadoMarca como falhou, sem nova tentativa.

A tela mostra o histórico de entregas de cada assinatura (menu ⋮ > Ver entregas), com status, código HTTP, duração, número de tentativas e o começo da resposta. Entregas que falharam ou foram abandonadas têm o botão Reenviar.

Desativação automática

Cada falha (inclusive cada tentativa que não deu certo) soma 1 no contador da assinatura, e uma entrega bem-sucedida zera o contador. Com 50 falhas seguidas, a assinatura é desativada e para de receber avisos. Entregas que estavam na fila de uma assinatura inativa são abandonadas.

Boas práticas​

  • Responda rápido. Devolva 200 assim que receber e processe depois (fila, tarefa em segundo plano). O limite é de 10 segundos.
  • Não processe duas vezes. Guarde o X-Webhook-Delivery-Id já tratado; a mesma entrega pode chegar mais de uma vez.
  • Não dependa da ordem. Avisos de eventos diferentes podem chegar fora da ordem em que aconteceram; compare o timestamp do corpo.
  • Valide a assinatura sempre que tiver cadastrado um segredo (veja Validação).
  • Responda 4xx só para erro definitivo. Um 4xx encerra as tentativas daquela entrega; para falha temporária, responda 5xx ou 429.
Ainda com dúvida?

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