Webhook Événements et avertissements de liquidation
Types d’événements de commerçant Webhook, identités d’idempotence, champs d’avertissement de liquidation et exemples de résultats de fonds.
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 le rappel configuré unique du commerçant URL (agents.webhook_url). Envoi sur le corps event ; aucun avertissement distinct URL n’est requis. Les exemples montrent la structure de la charge utile et ne doivent pas être utilisés pour injecter des données dans un environnement de test.
Événements et idempotence
L’événement d’avertissement du commerçant est liquidation.warning ; l’utilisateur WebSocket data.event reste LIQUIDATION_WARNING. Gardez les deux canaux distincts.
Notifications historiques des marchands utilisées LIQUIDATION_WARNING. Les charges utiles gelées conservent leur corps d’origine lors des tentatives, les récepteurs doivent donc reconnaître les deux noms. Si les enregistrements professionnels existants utilisent un préfixe de clé d’avertissement en majuscule, conservez la clé d’origine ou vérifiez les deux clés pendant la migration pour éviter de traiter à nouveau la notification.
Le WebhookVerifier.idempotencyKey actuel extrait uniquement orderType:orderId:targetStatus pour les événements de fonds et renvoie une chaîne vide pour les charges utiles d’avertissement. Aucun nouvel artefact SDK contenant des méthodes d’assistance d’avertissement n’a été publié avec cette mise à jour de la documentation. Continuez à utiliser la méthode verify existante pour vérifier le corps brut de l’avertissement. Après les vérifications de signature et de propriété, le code commercial du commerçant doit reconnaître les deux noms d’événements, valider que notificationId est une chaîne d’entiers décimaux positifs et construire liquidation.warning:<notificationId>. N’utilisez jamais une clé de déduplication vide et n’exigez jamais que les avertissements contiennent des champs d’ordre de fonds.
Conservez la déduplication au sein du commerçant et de la portée environment et validez-la de manière atomique avec le traitement métier. Les notifications FIRST / UPGRADE / REMINDER avec des valeurs notificationId différentes sont indépendantes ; ne les supprimez pas en les regroupant par utilisateur, épisode ou eventType. Une clé vide signifie qu’une identité valide n’a pas pu être extraite. Le SDK renvoie uniquement une clé d’assistance ; il ne conserve pas les enregistrements et n’effectue pas de traitement commercial. Enregistrez la même identité avec un corps différent comme un conflit ; n’écrasez pas le corps traité.
Champs d’avertissement de liquidation et exemple
Exemple de résultat de transfert
Les rappels de fonds conservent leurs types existants : orderId et agentId sont des nombres JSON ; amount et platformUserId sont des chaînes. N’appliquez pas la convention de chaîne d’avertissement agentId aux rappels de fonds. Lisez de grands entiers sans perte de précision en utilisant des types entiers/décimaux. completedAt est UTC RFC3339 ; ts correspond aux secondes Unix.
Exemple de résultat d’inversion
Exemple d’ordre de fonds à l’état mort
Ces exemples montrent uniquement le protocole. Pour FAILED, rejectCode, rejectMessage et failReason reflètent le rejet réel. Le nom de l’événement à lui seul ne prouve pas que les fonds ont été crédités.