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

Os Webhooks notificam o backend parceiro sobre alterações assíncronas no estado do negócio. Como a entrega pode ser tentada novamente, cada recetor 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-Agent-Timestamp	Carimbo de data e hora do Unix em segundos.
X-Agente-Nonce	Sem proteção contra repetições.
X-Agent-Signature	HMAC-SHA256 assinatura.

timestamp + nonce + rawBody

Use o corpo bruto do pedido recebido ao longo de HTTP ao reconstruir o valor assinado. Analisar e voltar a serializar 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 temporal, nonce e assinatura.
Capturar o corpo bruto do pedido não modificado.
Construir timestamp + nonce + rawBody.
Calcular HMAC-SHA256 com o parceiro API segredo.
Compare as assinaturas calculadas e recebidas usando uma comparação em tempo constante.
Aplicar as verificações aprovadas de carimbo temporal e não reutilização.
Analisar e processar o evento apenas após o sucesso da verificação.

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

Idempotência da ordem

Caso	Condução
Pedido inicial de transferência	Crie uma agentOrderNoglobalmente única.
HTTP pausa	Consulta o agentOrderNo original antes de criar um novo.
PROCESSING resposta	Aguarde pelo estado do webhook ou da encomenda de consulta.
Webhook repetido	Desduplicar por chave de idempotência e estado final.

Registo recomendado de idempotência

Armazene informação suficiente para reconhecer uma entrega repetida e recuperar em segurança:

Campo	Finalidade
Chave do evento ou do negócio	Identifica de forma única a notificação ou operação.
Número de encomenda do parceiro	Liga o evento ao pedido original.
Hash da carga útil	Ajuda a identificar cargas úteis repetidas em conflito.
Estado atual do processamento	Distingue trabalhos recebidos, processados, bem-sucedidos e falhados.
Estado final do negócio	Impede que uma ação terminal seja aplicada duas vezes.
Carimbo temporal processado	Apoia políticas de investigação e retenção.

Comprometa o registo de alteração do 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, a ordem ou a alteração do utilizador.

Regra do tempo limite e da retentativa

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

Lista de verificação de produção

Verificar a assinatura antes de JSON análise ou processamento empresarial.
Preservar o corpo bruto independentemente da carga útil analisada.
Rejeitar pedidos obsoletos ou reproduzidos de acordo com a política de integração aprovada.
Tornar o processamento de eventos seguro para entregas repetidas e fora de ordem.
Registar IDs de eventos, números de encomenda dos parceiros, resultados de processamento e tempo de pedido.
Redigir segredos e valores de assinatura dos registos e anexos de suporte.

Segredos e HMAC Assinaturas

Proteja o segredo API usado para verificação de pedidos e webhooks.

Agent SDK Visão Geral

Revê todo o fluxo de trabalho de integração do backend.

SDK Resolução de problemas