Verificação de Assinatura em Webhook e Idempotência

Webhooks notificam um backend parceiro sobre mudanças assíncronas no estado do negócio. Como a entrega pode ser tentada novamente, todo receptor deve verificar a assinatura antes de analisar dados confiáveis e deve processar o evento de forma idempotente.

Cabeçalhos Webhook

Cabeçalho	Descrição
X-Agente-Timestamp	Carimbo de data e hora do Unix em segundos.
X-Agente-Nonce	Proteção contra repetição.
X-Agent-Signature	HMAC-SHA256 assinatura.

timestamp + nonce + rawBody

Use o corpo bruto exato da solicitação recebido sobre HTTP ao reconstruir o valor assinado. Analisar e reserializar JSON primeiro pode alterar a ordem dos espaços em branco ou dos campos e produzir uma assinatura diferente.

Fluxo de verificação

Leia os cabeçalhos de carimbo de data/hora, nonce e assinatura.
Capturar o corpo bruto da solicitação não modificado.
Construa timestamp + nonce + rawBody.
Calcule HMAC-SHA256 com o parceiro API segredo.
Compare as assinaturas calculadas e recebidas usando uma comparação em tempo constante.
Aplique as verificações aprovadas de atualização e reutilização de data.
Analisar e processar o evento somente após o sucesso da verificação.

Quando um verificador oficial de Agent SDK estiver disponível, use-o em vez de manter um código de assinatura independente.

Idempotência de ordem

Caso	Dirigibilidade
Pedido inicial de transferência	Crie uma agentOrderNoglobalmente única.
HTTP tempo	Consulte a agentOrderNo original antes de criar uma nova.
PROCESSING resposta	Espere pelo status do webhook ou da ordem de consulta.
Webhook repetido	Deduplicar pela chave de idempotência e status final.

Registro recomendado de idempotência

Armazene informações suficientes para reconhecer uma entrega repetida e recuperar com segurança:

Campo	Propósito
Chave de evento ou negócio	Identifica de forma única a notificação ou operação.
Número do pedido do parceiro	Conecta o evento ao pedido original.
Hash da carga útil	Ajuda a identificar cargas úteis repetidas e conflitantes.
Estado atual de processamento	Distingue trabalhos recebidos, processando, bem-sucedidos e fracassados.
Status final do negócio	Impede que uma ação terminal seja aplicada duas vezes.
Carimbo de data processado	Apoia políticas de investigação e retenção.

Comprometa o registro de mudança de negócio e de idempotência na mesma transação sempre que possível. Um evento repetido deve devolver o resultado já conhecido em vez de aplicar novamente o saldo, ordem ou alteração do usuário.

Regra do tempo limite e da tentativa de retentar

Um tempo de espera HTTP não prova que a solicitação original falhou. Consulte a operação usando o agentOrderNooriginal ou espere pelo webhook antes de decidir se outra ação é necessária. Criar um novo número de ordem de negócio após cada timeout pode causar movimentos duplicados de fundos.

Checklist de produção

Verificar a assinatura antes de JSON análise ou processamento empresarial.
Preservar o corpo bruto independentemente da carga útil analisada.
Rejeitar solicitações obsoletas ou reproduzidas de acordo com a política de integração aprovada.
Tornar o processamento de eventos seguro para entregas repetidas e fora de ordem.
Registrar IDs de eventos, números de pedido de parceiros, resultado de processamento e tempo de solicitação.
Redigir segredos e valores de assinatura de logs e anexos de suporte.

Segredos e HMAC Assinatura

Proteja o segredo API usado para verificação de solicitações e webhooks.

Agent SDK Visão Geral

Revise o fluxo completo de integração do backend.

SDK Solução de problemas