Webhook Verificação de assinatura e idempotência
Verifique os corpos Webhook em bruto, confirme utilizando os códigos de estado HTTP e lide com novas tentativas e duplicados de forma fiável.
Esta página segue Agent Java SDK WEBHOOKS.md no commit fa6c7b6. Esta é uma atualização apenas de documentação; nenhum novo artefacto SDK contendo métodos auxiliares de aviso foi lançado.
Todos os quatro tipos de eventos utilizam um callback 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 âmbito 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 utilizador, episódio ou eventType. Uma chave de idempotência vazia não pode ser utilizada para desduplicação. O SDK apenas devolve uma chave auxiliar; não persiste nem processa dados de negócio. Registar a mesma identidade com um corpo diferente como conflito; não substitua o corpo processado.
Verificação e receção de assinatura
Utilize 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 forma fiá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.
Devolver HTTP 2xx após concluir o processamento ou confirmar um duplicado idêntico; retornar não-2xx em caso de falha. O remetente do aviso tem um tempo limite de HTTP de 5 segundos e um máximo de 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 fidedigna; o trabalho comercial de longa duração pode utilizar as tarefas persistentes do próprio comerciante.
As notificações do comerciante não dependem do estado online do utilizador. Os push do utilizador da plataforma são apenas entregues online com o melhor esforço, sem repetição offline; a fase um não tem caixa de entrada de notificações.
Respostas bem-sucedidas e interrupção de novas tentativas
Os retornos de chamada de fundos e os avisos de liquidação utilizam apenas o código de estado HTTP para determinar o sucesso da entrega. O emissor 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, e não requisitos de protocolo. 202 Accepted também interrompe novas tentativas da plataforma, por isso, devolva-a apenas depois de guardar a notificação de forma fiá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 de o processamento comercial ter sido concluído ou a notificação ter sido guardada de forma fiável na fila de pendências do próprio comerciante:
Quando não é necessário nenhum corpo de resposta:
Para uma notificação já processada com um corpo idêntico, ignore o processamento comercial duplicado e ainda assim devolva 2xx:
Exemplos de resposta a falhas
Se a base de dados estiver temporariamente indisponível e o comerciante não tiver concluído o processamento nem tiver guardado a notificação de forma fiável, devolva não-2xx para que a plataforma possa tentar novamente:
Rejeite uma assinatura inválida sem atualizar os dados comerciais ou os registos de desduplicação bem-sucedidos:
Estes ó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 subscrição, o conteúdo da notificação ou a configuração do comerciante.
Exemplo incorreto: a resposta seguinte ainda conta como entrega bem-sucedida. A plataforma não tentará novamente por causa de success:false.
Se a estrutura ou o gestor de exceções global agrupar falhas de negócio em HTTP 200, defina explicitamente o estado de falha correto no ponto de extremidade de retorno de chamada.
Reconhecimento fiá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ócio e registos de desduplicação bem-sucedidos numa transação ou guardar de forma fiável uma tarefa pendente → retornar 200/204 após o commit ser bem-sucedido. Não devolva 2xx nem marque a notificação como processada antes de uma gravação bem-sucedida na base de dados.
A entrega duplicada pode ainda 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. Os callbacks HTTP não garantem uma entrega única. Persista a desduplicação no âmbito do comerciante e environment. Utilização de fundos orderType:orderId:targetStatus; avisos utilizam 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, registar conflito e devolver não-2xx; não substitua o registo 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 registar uma notificação de fundos válida com targetStatus=FAILED, devolva 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 utilizando queryWalletTransfer e o ambiente do pedido original. Utilizações de financiamento status; as respostas originais de transferência de contrato utilizam orderStatus. Uma resposta HTTP ou code=0 bem-sucedida não prova, por si só, que os fundos foram movimentados.
As notificações explícitas de transferência de contrato simuladas incluem environment=SIMULATED. Verifique primeiro o corpo bruto e, em seguida, verifique o utilizador, o valor, a identidade do pedido e o ambiente em relação à ordem comercial local guardada.