Webhook de paiement crypto : traiter l’id et le status
Guide du webhook de paiement crypto : recevez le statut final en POST avec id et status, vérifiez l’en-tête x-api-key et mettez les commandes à jour.
Un webhook de paiement crypto indique à votre backend le statut final d’un paiement. Chez Qvard, c’est un POST contenant l’identifiant de votre commande et le statut, si bien que la logique de commande se met à jour sans interroger l’API en boucle.
Ce que le webhook transmet
Qvard appelle votre URL de webhook par une requête POST. Le corps contient l’id que vous avez envoyé à la création du paiement et le statut, par exemple paid. La requête transporte votre jeton x-api-key dans l’en-tête.
Vérifier l’en-tête x-api-key
Avant de faire confiance au message, comparez l’en-tête x-api-key avec le jeton de votre compte. Rejetez les requêtes sans cet en-tête, afin que personne ne puisse marquer une commande comme payée en appelant directement votre endpoint.
x-api-key: sk_live_…
{ "id": "order_1024", "status": "paid" }Mettre la commande à jour par id
Retrouvez la commande grâce à l’id du corps et modifiez son état selon le statut. Ne marquez une commande comme payée que lorsque le statut est paid, et ignorez les statuts que votre système ne gère pas.
Rendre le gestionnaire sûr en cas de répétition
Le même webhook peut arriver plus d’une fois. Enregistrez l’id et le statut déjà traités et ne faites rien si l’événement a déjà été pris en compte. Répondez par un code de succès une fois la modification enregistrée.
Répondre vite, mettre le travail lent en file
Confirmez le webhook dès que la commande est enregistrée. Envoyez les e-mails, factures et appels à l’entrepôt depuis une tâche de fond, pour qu’une étape lente ne provoque jamais de délai d’attente.
Tester avec une facture de démo
Créez une facture de démo, payez-la sur la page hébergée et vérifiez que votre endpoint reçoit le webhook avant la mise en production.
FAQ
Quelle est la différence entre la réponse de l’API et le webhook ?
La réponse de l’API confirme la création du paiement et renvoie un redirectUrl. Seul le webhook signale le statut final du paiement.
Que se passe-t-il si mon endpoint est indisponible ?
La livraison est relancée, votre gestionnaire doit donc être sûr en cas de répétition. Consultez régulièrement vos journaux et rapprochez les commandes restées en attente.
Puis-je faire confiance à un webhook sans x-api-key ?
Non. Vérifiez toujours l’en-tête x-api-key avant de modifier une commande.
Quels statuts dois-je traiter ?
Traitez paid pour les paiements réussis et considérez les autres statuts comme de l’information. La documentation de l’API liste l’ensemble des valeurs.
