Webhooks e recuperação de eventos

Passo 1 — Configurar um destino

Um administrador abre uma chave em API e integrações e adiciona um destino HTTP ou HTTPS. Recomenda-se HTTPS; a interface avisa sobre HTTP, IP direto e endereços locais sem impedir o registo. O middleware tem de alcançar o URL. Cada destino pertence à chave e tem um segredo próprio, apresentado apenas na criação ou rotação. Selecione os tipos de evento necessários. Rodar ou revogar a chave também afeta os seus destinos; prepare o recetor antes de ativar a entrega.

“Recetor pronto” significa URL e segredo configurados, não que já chegou um evento. Separe nos registos os comandos API de saída, as entregas webhook de entrada e a recuperação por GET /v1/events. Um PUT ou POST iniciado pelo backend não é um webhook recebido.

Confirme o emparelhamento comparando o URL exato exibido na chave com o do recetor e guarde o segredo devolvido. A API não o volta a mostrar. Só considere uma entrega live recebida depois de um POST assinado ser verificado; possuir localmente o segredo comprova configuração, não entrega.

Passo 2 — Verificar antes de processar

Cada entrega contém webhook-id, webhook-timestamp e webhook-signature. Standard Webhooks aplica HMAC-SHA256 aos bytes UTF-8 de webhook-id + "." + webhook-timestamp + ".", seguidos dos bytes exatos do corpo bruto. O segredo começa por whsec_ e inclui uma chave Base64. Compare em tempo constante a assinatura Base64 de uma entrada v1,.

Rejeite timestamps com mais de cinco minutos de desvio. Verifique antes de interpretar JSON. Confirme que o id do corpo coincide com webhook-id e persista-o antes dos efeitos operacionais. Responda rapidamente com 2xx.

As entregas são at least once e podem chegar fora de ordem. Elimine duplicados por ID. Um evento de conclusão inclui IDs e caminhos; obtenha os dados completos pela API autenticada. Os eventos principais são rental.departure.completed e rental.return.completed; correções e PDF pronto têm eventos separados. Consulte a definição OpenAPI Rental.

Passo 3 — Reconciliar após cada sinal

Após um webhook válido, releia o Rental ou o índice de relatórios. O JSON pode estar pronto antes do PDF; siga o fluxo 200/202 em Relatórios e provas. Não bloqueie indefinidamente à espera do webhook: a reconciliação periódica continua válida.

Passo 4 — Recuperar eventos perdidos

Use GET /v1/events com cursor e, se necessário, created_after. Os eventos permanecem 30 dias. Avance o cursor apenas após processar a página. A plataforma repete entregas falhadas até oito vezes em 48 horas; um administrador pode consultá-las e repeti-las em API e integrações.

Trate o feed como notificação e as rotas autenticadas como fonte do estado atual. Identidades e versões dos relatórios descreve o arquivo seguro.

Se não aparecer um evento assinado

1. Confirme que destino, chave e ambiente são os mesmos dos pedidos API.
2. Confirme a seleção de rental.departure.completed e rental.return.completed e o URL exato.
3. Consulte o histórico. Um estado não 2xx, timeout ou assinatura rejeitada indica falha do recetor; corrija uma chave desativada ou revogada antes de repetir.
4. Execute de imediato GET /v1/events para continuar o processamento.
5. Rode o segredo apenas se o recetor já não tiver o valor correspondente e atualize-o antes de repetir a entrega.

Ao pedir apoio, forneça ID do evento ou entrega e request_id; nunca envie o segredo.