Visão geral

Visão geral

O TermoWebhook é o hub central de eventos da Termotubos: recebe os avisos que cada sistema publica sobre os dados de que é dono e os entrega a todos os apps inscritos. Ele não tem regra de negócio: só recebe, valida, guarda e entrega.

Peças

• Aplicativos: os sistemas que publicam e recebem eventos. Cada um tem um segredo de publicação.
• Tipos de evento: o catálogo (pedido.faturado, cliente.atualizado…). Cada tipo tem um único aplicativo dono, o único que pode publicá-lo, e um prazo de retenção.
• Versões do esquema: o contrato de cada tipo em JSON Schema. Mudança compatível edita a versão; mudança que quebra vira versão nova. Situações: ativa, descontinuada e desligada.
• Assinaturas: qual aplicativo recebe qual tipo, em qual versão e em qual URL.
• Eventos: cada ocorrência publicada. O id é gerado pelo publicador (UUIDv7) e garante que o mesmo evento nunca entra duas vezes.
• Entregas: um evento para uma assinatura, com o histórico de cada tentativa.

O caminho de um evento

1. O dono publica em POST /eventos, assinando o corpo com HMAC.
2. O hub confere a assinatura, o envelope e os dados contra o JSON Schema. O que não passa é recusado (401 ou 422) e registrado com o motivo na tela de recusados.
3. Aceito, o hub grava o evento e cria uma entrega para cada assinatura daquela versão, na mesma transação. Repetido, responde 200 e não faz mais nada.
4. O entregador faz o POST para cada assinante, também assinado com HMAC. Falhou, tenta de novo depois de 1 min, 5 min, 30 min, 2 h e 12 h. Esgotou, a entrega vai para a fila de erro.
5. Na fila de erro, a equipe corrige o aplicativo e reprocessa pelo painel.

Painel

Visão geral, eventos, entregas, fila de erro, recusados, reprocessamentos, aplicativos, tipos de evento com as versões, assinaturas e colaboradores. O acesso é pelo TermoAuth, com permissões por área (monitoramento, aplicativos, tipos de evento, assinaturas e colaboradores).

O backend é em Rust (Axum + SQLx + PostgreSQL) e o frontend em SvelteKit.