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.
- No menu lateral, seção Sistema, entre em Integrações > Inscrição de Webhook.
- Clique em Novo e preencha:
| Campo | Para que serve | Obrigatório |
|---|---|---|
| URL de destino | Endereç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 assinados | Quais 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 personalizados | Pares nome/valor enviados em todo aviso (por exemplo, um token que o seu sistema exige). | Não |
- 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çalho | Conteúdo |
|---|---|
X-Webhook-Event | Nome do evento. |
X-Webhook-Delivery-Id | Identificador da entrega. É o mesmo em todas as tentativas da mesma entrega: use-o para não processar o mesmo aviso duas vezes. |
X-Webhook-Timestamp | Momento do envio desta tentativa, 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. |
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 responde | O que o Tesselys faz |
|---|---|
2xx em até 10 segundos | Marca 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 segundos | Agenda nova tentativa: depois de 1 minuto, 5 minutos, 30 minutos e 2 horas. |
| Quatro novas tentativas sem sucesso | Marca como abandonada. |
| URL que aponta para endereço interno ou privado | Marca 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.
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
200assim 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-Idjá 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
timestampdo corpo. - Valide a assinatura sempre que tiver cadastrado um segredo (veja Validação).
- Responda
4xxsó para erro definitivo. Um4xxencerra as tentativas daquela entrega; para falha temporária, responda5xxou429.
A nossa equipe ajuda você a configurar e usar esse recurso.