Webhook Verificação de assinatura e idempotência
Verifique corpos Webhook brutos, confirme usando códigos de status HTTP e lide com novas tentativas e duplicatas de maneira confiável.
Esta página segue Agent Java SDK WEBHOOKS.md no commit fa6c7b6. Esta é uma atualização apenas de documentação; nenhum novo artefato SDK contendo métodos auxiliares de aviso foi lançado.
Todos os quatro tipos de eventos usam um retorno de chamada de comerciante URL e são despachados pelo corpo event. Ver Webhook Eventos e avisos de liquidação para campos de eventos e exemplos de carga útil.
Webhook cabeçalhos
Idempotência de evento
Persista a desduplicação no escopo do comerciante e environment, atomicamente com o processamento de negócios. Valores notificationId diferentes identificam notificações FIRST / UPGRADE / REMINDER independentes; não descarte notificações agrupando por usuário, episódio ou eventType. Uma chave de idempotência vazia não pode ser usada para desduplicação. O SDK retorna apenas uma chave auxiliar; ele não persiste nem processa dados de negócios. Registrar a mesma identidade com corpo diferente como conflito; não substitua o corpo processado.
Verificação e recebimento de assinatura
Use o segredo do comerciante API para calcular a assinatura hexadecimal HMAC-SHA256 de timestamp + nonce + rawBody. Verifique os bytes originais recebidos; não formate JSON, renomeie os campos ou serialize novamente o corpo primeiro.
Verifique primeiro a assinatura e depois verifique a janela de tempo (recomendado ±300 segundos), o comerciante e o ambiente. Em seguida, extraia a identidade de idempotência e trate a notificação de maneira confiável. Preservar valores de eventos desconhecidos para diagnóstico; nunca os interprete como sucesso de fundos. O auxiliar de verificação não executa verificações de janela de tempo, propriedade ou desduplicação persistente.
Retornar HTTP 2xx após concluir o processamento ou confirmar uma duplicata idêntica; retornar não-2xx em caso de falha. O remetente do aviso tem um tempo limite de HTTP de 5 segundos e no máximo 8 tentativas. As novas tentativas retêm o corpo congelado; apenas o carimbo de data/hora da assinatura e o nonce são alterados. Responder prontamente após aceitação confiável; o trabalho comercial de longa duração pode usar as tarefas persistentes do próprio comerciante.
As notificações do comerciante não dependem do status online do usuário. Os push do usuário da plataforma são apenas entregues on-line com o melhor esforço, sem repetição off-line; a fase um não tem caixa de entrada de notificação.
Respostas bem-sucedidas e interrupção de novas tentativas
Retornos de chamada de fundos e avisos de liquidação usam apenas o código de status HTTP para determinar o sucesso da entrega. O remetente não interpreta o corpo da resposta code, success, result ou message e não requer uma resposta fixa OK / success.
O corpo da resposta pode estar vazio, texto ou JSON. Os campos de exemplo result são informativos para o comerciante, não requisitos de protocolo. 202 Accepted também interrompe novas tentativas da plataforma, portanto, retorne-a somente depois de salvar a notificação de forma confiável na fila de tarefas persistentes do comerciante, e não apenas iniciar uma tarefa assíncrona na memória.
Exemplos de respostas bem-sucedidas
Depois que o processamento comercial for concluído ou a notificação tiver sido salva de forma confiável na fila de pendências do próprio comerciante:
Quando nenhum corpo de resposta é necessário:
Para uma notificação já processada com corpo idêntico, ignore o processamento comercial duplicado e ainda retorne 2xx:
Exemplos de resposta a falhas
Se o banco de dados estiver temporariamente indisponível e o comerciante não tiver concluído o processamento nem salvou a notificação de forma confiável, retorne não-2xx para que a plataforma possa tentar novamente:
Rejeite uma assinatura inválida sem atualizar dados comerciais ou registros de desduplicação bem-sucedidos:
Esses órgãos de resposta não alteram as decisões de novas tentativas. Não espere que um 401 ou 409 interrompa permanentemente as novas tentativas; investigue a assinatura, o conteúdo da notificação ou a configuração do comerciante.
Exemplo incorreto: a resposta a seguir ainda conta como entrega bem-sucedida. A plataforma não tentará novamente por causa de success:false.
Se a estrutura ou o manipulador de exceção global agrupar falhas de negócios em HTTP 200, defina explicitamente o status de falha correto no ponto de extremidade de retorno de chamada.
Reconhecimento confiável e entrega duplicada
Ordem recomendada: verificar a assinatura e verificar o horário/comerciante/ambiente → extrair a identidade de idempotência → processar dados de negócios e registros de desduplicação bem-sucedidos em uma transação ou salvar de forma confiável uma tarefa pendente → retornar 200/204 após o commit ser bem-sucedido. Não retorne 2xx nem marque a notificação como processada antes de uma gravação bem-sucedida no banco de dados.
A entrega duplicada ainda pode ocorrer após o processamento do comerciante ser bem-sucedido: a resposta pode ser perdida ou a plataforma pode receber 2xx, mas não persistir SUCCESS. Retornos de chamada HTTP não garantem entrega única. Persista a desduplicação no escopo do comerciante e environment. Uso de fundos orderType:orderId:targetStatus; avisos usam liquidation.warning:notificationId. Para um corpo idêntico já processado, devolva 2xx sem creditar fundos ou emitir um lembrete novamente. Para a mesma identidade com órgão diferente, registre conflito e retorne não-2xx; não substitua o registro original.
O sucesso da confirmação significa que o comerciante recebeu/processou a notificação, e não que a operação de fundos foi bem-sucedida. Após registrar uma notificação de fundos válida com targetStatus=FAILED, retorne também 2xx; uma falha no pedido não é motivo para rejeitar a confirmação da notificação.
Limites de financiamento e ambientais
A transferência original do Contrato webhook e o fluxo queryOrder não se aplicam automaticamente ao Financiamento. Confirme as operações de financiamento usando queryWalletTransfer e o ambiente do pedido original. Usos de financiamento status; as respostas originais de transferência de contrato usam orderStatus. Uma resposta HTTP ou code=0 bem-sucedida não prova, por si só, que os fundos foram movimentados.
Notificações explícitas de transferência de contrato simuladas incluem environment=SIMULATED. Verifique primeiro o corpo bruto e, em seguida, verifique o usuário, o valor, a identidade do pedido e o ambiente em relação à ordem comercial local salva.