Webhooks de integração

Como avisar um sistema externo no instante em que algo acontece aqui. Você inscreve um endereço para um evento, e a plataforma passa a chamá-lo — com trilha de cada entrega.

O tenant registra um ENDPOINT (uma URL sua) para ser AVISADO por HTTP toda vez que um evento de negócio acontece no Tenka — contrato assinado, título pago, FCA aberto. Cada aviso é um POST assinado com HMAC-SHA256 do corpo usando um SEGREDO que só você e o Tenka conhecem (header X-Tenka-Signature): o seu sistema confere a assinatura e sabe que a chamada veio do Tenka e não foi adulterada. Aqui você cria a inscrição (url + evento + segredo), ativa/desativa, acompanha a TRILHA de entregas (PENDENTE → ENTREGUE | FALHA, com o nº de tentativas e o backoff), e pode disparar um evento de TESTE ou reenfileirar uma entrega que falhou. O evento "*" inscreve todos. Distinta dos webhooks internos de cobrança (Asaas).

Cada entrega é assinada com o segredo da inscrição. Quem recebe DEVE conferir essa assinatura antes de confiar no conteúdo — sem isso, qualquer um que descubra a sua URL consegue enviar um evento falso para ela.

O botão de teste manda um evento real para o seu endpoint agora, sem esperar o fato acontecer. É a forma mais rápida de descobrir erro de URL, de firewall ou de assinatura — antes que o primeiro evento de verdade se perca na fila.

A API pública /api/v1 é congelada: nada some nem muda de tipo; mudança que quebra vai para /v2. O SDK sai do próprio contrato: /api/v1/sdk/tenka.js e /api/v1/sdk/tenka.py. O histórico de versões está no documento API-CHANGELOG da Biblioteca.

Endpoint fora do ar não perde o evento: a plataforma tenta de novo, espaçando as tentativas. A trilha mostra o status e quantas tentativas houve — é por ali que se descobre que a integração "parou" porque o certificado do outro lado venceu.

O log de eventos mostra tudo que a conta enviou, em todas as inscrições, com filtro por evento e situação. Reenviar cria uma entrega nova com o mesmo conteúdo e o cabeçalho X-Tenka-Replay-Of com o id da original, para o sistema que recebe não duplicar. Toda entrega leva X-Tenka-Event-Version com a versão do contrato.

Quais sistemas meus o Tenka avisa quando algo acontece — e as entregas estão chegando? Registre um endpoint (uma URL sua) por evento de negócio e o Tenka manda um POST assinado com HMAC-SHA256 do corpo (header X-Tenka-Signature), que o seu sistema confere para saber que a chamada veio daqui e não foi adulterada. A trilha de entregas mostra PENDENTE, ENTREGUE ou FALHA, com o número de tentativas e o backoff; dá para disparar um evento de teste e reenfileirar uma entrega que falhou. O evento * inscreve o endpoint em todos os eventos.