1
Déclarez l'endpoint
Dans l’onglet Webhooks de la console Développeurs, ajoutez une URL HTTPS publique et cochez les événements voulus. Mercy Pay affiche alors le secret de signature (
whsec_…). Copiez-le dans vos secrets. Vous pourrez le réafficher plus tard depuis la console, après avoir confirmé votre mot de passe.2
Vérifiez la signature
Chaque requête porte l’en-tête Vérifiez le corps tel qu’il est reçu, avant tout
MercyPay-Signature, de la forme t=1791022800,v1=5257a869…. t est l’heure d’envoi, v1 le HMAC-SHA256 en hexadécimal de {t}.{corps brut}, calculé avec votre secret. Refusez une signature de plus de 5 minutes : elle protège contre le rejeu d’une ancienne requête. Voir Sécurité des webhooks.JSON.parse.3
Répondez vite, traitez après
Répondez
2xx dès que la signature est validée, avant de lancer un traitement lourd. Mercy Pay n’attend que 10 secondes. Passé ce délai, ou sur une réponse qui n’est pas 2xx, la livraison est considérée en échec et reprise plus tard.Si votre serveur n’a accepté aucun événement pendant ces 3 jours, l’endpoint est désactivé et les développeurs de votre boutique reçoivent un e-mail. Corrigez le serveur, réactivez l’endpoint, puis cliquez sur Relancer les échecs dans la console. Les événements restent consultables avec
GET /api/v1/events.4
Dédupliquez par identifiant
Une même livraison peut arriver deux fois, par exemple si le réseau coupe juste après votre
2xx. Chaque événement porte un id (evt_…), répété dans l’en-tête MercyPay-Event-Id : enregistrez ceux que vous avez déjà traités et ignorez les doublons.