Webhooks

Entrega segura e idempotente de confirmações e mudanças de estado.

Visão geral

Webhooks permitem que um sistema autorizado informe eventos à kroz sem depender de consulta contínua.

Exemplos incluem confirmação de pagamento, mudança de estado de uma cobrança ou atualização cadastral relevante. Os eventos habilitados dependem da integração contratada.

URLs, credenciais e formatos executáveis são entregues em canal controlado durante o onboarding.

Contrato de entrega

Todo evento deve conter, no mínimo:

• identificador único;
• tipo e versão;
• data de ocorrência;
• referência do recurso relacionado;
• contexto da organização autorizada;
• dados necessários para processar a mudança.

Não inclua credenciais nem dados pessoais que não sejam necessários para o evento.

Autenticidade

O receptor deve validar a origem antes de aceitar o conteúdo.

Controles esperados:

• HTTPS;
• segredo ou mecanismo de assinatura exclusivo do ambiente;
• comparação segura da assinatura;
• tolerância de tempo quando houver timestamp assinado;
• rotação e revogação documentadas;
• rejeição de eventos que não possam ser autenticados.

Nunca registre o segredo de assinatura em logs.

Idempotência e deduplicação

Um mesmo evento pode ser entregue mais de uma vez. O processamento deve produzir o mesmo resultado sem duplicar efeitos.

Fluxo recomendado:

1. autentique a origem;
2. valide a estrutura e a versão;
3. registre o identificador do evento;
4. verifique se ele já foi processado;
5. produza o efeito uma única vez;
6. preserve o resultado para responder a reenvios.

Ordem dos eventos

Não presuma que eventos diferentes chegarão na mesma ordem em que ocorreram.

Use estado atual, data de ocorrência e regras de transição para decidir se um evento pode ser aplicado. Quando a ordem não puder ser resolvida com segurança, encaminhe o caso para conciliação.

Respostas e repetição

O receptor deve confirmar rapidamente que o evento foi aceito para processamento. Trabalho demorado deve continuar fora da resposta imediata.

Em caso de falha temporária, o emissor pode repetir a entrega com intervalo progressivo e limite definido. Erros permanentes de autenticação ou validação não devem ser repetidos indefinidamente.

Evolução do formato

Eventos possuem versão. Consumidores devem:

• validar campos obrigatórios;
• tolerar campos adicionais quando forem compatíveis;
• rejeitar versões desconhecidas que alterem o significado;
• testar mudanças em homologação;
• coordenar alterações incompatíveis.

Observabilidade

Registre sem expor dados desnecessários:

• identificador do evento;
• tipo e versão;
• horário de recebimento;
• resultado da autenticação;
• resultado do processamento;
• tentativas e motivo da falha;
• identificador de correlação da operação.

Checklist de homologação

• origem autenticada;
• segredo separado por ambiente;
• evento duplicado testado;
• entrega fora de ordem testada;
• timeout e repetição testados;
• payload inválido rejeitado;
• logs revisados para dados e segredos;
• conciliação preparada para exceções;
• procedimento de rotação e revogação validado.

Relacionado

• Referência de API: princípios da integração
• Integração financeira: responsabilidades das camadas
• Conciliação: tratamento de diferenças
• Auditoria e prova: registro dos eventos