Webhook Vérification de signature et idempotence

Cette page suit Agent Java SDK WEBHOOKS.md au commit fa6c7b6. Il s’agit d’une mise à jour de documentation uniquement ; aucun nouvel artefact SDK contenant des méthodes d’assistance d’avertissement n’a été publié.

Les quatre types d’événements utilisent un rappel du commerçant URL et sont distribués par le corps event. Voir Webhook Événements et avertissements de liquidation pour les champs d’événements et les exemples de charges utiles.

Webhook en-têtes

timestamp + nonce + rawBody

Idempotence des événements

Persistance de la déduplication au sein du commerçant et de la portée environment, de manière atomique avec le traitement métier. Différentes valeurs notificationId identifient des notifications FIRST / UPGRADE / REMINDER indépendantes ; ne supprimez pas les notifications en les regroupant par utilisateur, épisode ou eventType. Une clé d’idempotence vide ne peut pas être utilisée pour la déduplication. Le SDK renvoie uniquement une clé d’assistance ; il ne persiste pas et ne traite pas les données commerciales. Enregistrez la même identité avec un corps différent comme un conflit ; n’écrasez pas le corps traité.

Vérification et réception de signature

Utilisez le secret du marchand API pour calculer la signature hexadécimale HMAC-SHA256 de timestamp + nonce + rawBody. Vérifiez les octets originaux reçus ; ne formatez pas JSON, ne renommez pas les champs ou ne resérialisez pas le corps en premier.

Vérifiez d’abord la signature, puis vérifiez la fenêtre de temps (recommandée ± 300 secondes), le commerçant et l’environnement. Extrayez ensuite l’identité d’idempotence et gérez la notification de manière fiable. Conserver les valeurs d’événements inconnus pour le diagnostic ; ne les interprétez jamais comme un succès financier. L’assistant de vérification n’effectue pas de contrôle de fenêtre temporelle, de propriété ou de déduplication persistante.

Renvoyez HTTP 2xx après avoir terminé le traitement ou confirmé un duplicata identique ; renvoie non-2xx en cas d’échec. L’expéditeur de l’avertissement dispose d’un délai d’attente de HTTP de 5 secondes et d’un maximum de 8 tentatives. Les tentatives conservent le corps gelé ; seuls l’horodatage de la signature et le changement occasionnel. Répondez rapidement après une acceptation fiable ; le travail commercial de longue durée peut utiliser les propres tâches persistantes du commerçant.

Les notifications des commerçants ne dépendent pas du statut en ligne de l’utilisateur. Les push des utilisateurs de la plateforme sont uniquement diffusés en ligne, au mieux, sans rediffusion hors ligne ; la première phase n’a pas de boîte de réception de notification.

Réponses réussies et tentatives d’arrêt

Les rappels de fonds et les avertissements de liquidation utilisent uniquement le code d’état HTTP pour déterminer le succès de la livraison. L’expéditeur n’interprète pas le corps de la réponse code, success, result ou message, et n’exige pas de réponse fixe OK / success.

Le corps de la réponse peut être vide, texte ou JSON. Les exemples de champs result sont informatifs pour le commerçant, et non des exigences de protocole. 202 Accepted arrête également les nouvelles tentatives de la plate-forme, donc ne la renvoyez qu’après avoir enregistré de manière fiable la notification dans la file d’attente des tâches persistantes du commerçant, et pas simplement en démarrant une tâche asynchrone en mémoire.

Exemples de réponses réussies

Une fois le traitement commercial terminé ou lorsque la notification a été enregistrée de manière fiable dans la file d’attente en attente du commerçant :

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"RECEIVED"}

Lorsqu’aucun corps de réponse n’est nécessaire :

HTTP/1.1 204 No Content

Pour une notification déjà traitée avec un corps identique, ignorez le traitement commercial en double et renvoyez quand même 2xx :

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"DUPLICATE"}

Exemples de réponses aux échecs

Si la base de données est temporairement indisponible et que le commerçant n’a pas terminé le traitement ni enregistré la notification de manière fiable, renvoyez non-2xx afin que la plateforme puisse réessayer :

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"result":"FAILED","message":"temporary storage failure"}

Rejetez une signature non valide sans mettre à jour les données commerciales ou les enregistrements de déduplication réussie :

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"result":"INVALID_SIGNATURE"}

Ces organismes de réponse ne modifient pas les décisions de nouvelle tentative. Ne vous attendez pas à ce qu’un 401 ou un 409 arrête définitivement les tentatives ; enquêtez sur la signature, le contenu de la notification ou la configuration du commerçant.

Exemple incorrect : la réponse suivante compte toujours comme une livraison réussie. La plateforme ne réessayera pas en raison de success:false.

HTTP/1.1 200 OK
Content-Type: application/json
{"success":false,"code":500,"message":"processing failed"}

Si le framework ou le gestionnaire d’exceptions global encapsule les échecs métier dans HTTP 200, définissez explicitement l’état d’échec correct au niveau du point de terminaison de rappel.

Accusé de réception fiable et livraison en double

Ordre recommandé : vérifier la signature et vérifier l’heure/le commerçant/l’environnement → extraire l’identité d’idempotence → traiter les données commerciales et les enregistrements de déduplication réussis dans une transaction, ou enregistrer de manière fiable une tâche en attente → renvoyer 200/204 une fois la validation réussie. Ne renvoyez pas 2xx et ne marquez pas la notification traitée avant une écriture réussie dans la base de données.

Une livraison en double peut toujours se produire une fois le traitement réussi par le commerçant : la réponse peut être perdue ou la plate-forme peut recevoir 2xx mais ne pas persister SUCCESS. Les rappels HTTP ne garantissent pas une livraison unique. Conserver la déduplication au sein du commerçant et dans la portée de environment. Utilisation des fonds orderType:orderId:targetStatus ; les avertissements utilisent liquidation.warning:notificationId. Pour un corps identique déjà traité, renvoyez 2xx sans créditer de fonds ni émettre de nouveau rappel. Pour la même identité avec un corps différent, enregistrez un conflit et renvoyez non-2xx ; n’écrasez pas l’enregistrement original.

L’accusé de réception réussi signifie que le commerçant a reçu/traité la notification, et non que l’opération de fonds a réussi. Après avoir enregistré une notification de fonds valide avec targetStatus=FAILED, renvoyez également 2xx ; un échec de commande ne constitue pas une raison pour rejeter l’accusé de réception de la notification.

Limites du financement et de l’environnement

Les flux de transfert de contrat d’origine webhook et queryOrder ne s’appliquent pas automatiquement au financement. Confirmez les opérations de financement en utilisant queryWalletTransfer et l’environnement de commande d’origine. Le financement utilise status ; Les réponses originales au transfert de contrat utilisent orderStatus. Une réponse réussie HTTP ou code=0 ne prouve pas en soi que les fonds ont été déplacés.

Les notifications explicites de transfert de contrat simulées incluent environment=SIMULATED. Vérifiez d’abord le corps brut, puis vérifiez l’utilisateur, le montant, l’identité de la commande et l’environnement par rapport à la commande commerciale locale enregistrée.

Guide de récupération du financement · Guide environnement