Skip to main content
Voici les étapes à suivre pour intégrer les webhooks :
1

Créer un point de terminaison HTTP pour recevoir les requêtes des webhooks.

Ce point de terminaison doit accepter des requêtes POST comme celle ci-dessous :
  • URL : https://website.com/webhook_payment (HTTPS obligatoire)
  • MÉTHODE : POST
  • EN-TÊTES :
  • CORPS :
Voici un exemple de webhook envoyé pour un événement payment_intent.created. Le champ data contient l’objet concerné par l’événement, owner correspond à votre identifiant marchand et id identifie l’événement.
2

Enregistrer ce point de terminaison auprès de l'API HUB2 et l'abonner à des événements.

L’API HUB2 dispose d’un point de terminaison dédié à cette action. Appelez-le avec le corps suivant :
Exemples de code :
Le webhook est créé dans l’environnement (live ou sandbox) indiqué dans l’en-tête Environment. L’API HUB2 répond avec le code HTTP 201 et un corps tel que :
Cette réponse contient le secret associé au webhook : "secret": "whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX". Il n’est renvoyé qu’une seule fois, à la création.
Conservez ce secret en lieu sûr : il est nécessaire pour vérifier l’intégrité de chaque webhook reçu.Pour plus de détails, consultez la référence de l’API Webhooks : Créer un webhook.
3

Vérifier la signature du webhook.

Cette étape est obligatoire : elle garantit que personne ne peut vous envoyer de faux webhooks.L’ignorer laisse une faille qu’une personne malveillante pourrait exploiter, par exemple pour faire valider ses propres transactions.
Pour vous assurer qu’un webhook provient bien de l’API HUB2, vérifiez la signature de son corps (payload).

a. Récupérer le secret du webhook.

Ce secret a été renvoyé à l’étape 2 ("secret": "whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" dans l’exemple).

b. Signer le payload.

Prenez le corps de la requête POST envoyée par HUB2 (voir l’étape 1) sous forme de chaîne de caractères, tel que reçu, et calculez son HMAC-SHA256 avec le secret comme clé, encodé en hexadécimal minuscule.Exemples selon le langage de programmation :
Signez le corps brut tel que reçu, avant toute désérialisation. Désérialiser le JSON puis le resérialiser peut modifier la chaîne (espaces, ordre des clés, échappement des caractères) et produire une signature différente.

c. Vérifier la signature.

Enfin, comparez la signature calculée à celle envoyée par HUB2 dans les en-têtes de la requête :
  • Hub2-Signature : nom de l’en-tête (les noms d’en-têtes HTTP ne sont pas sensibles à la casse).
  • s1 : signature calculée avec le secret actuel.
  • s0 : signature calculée avec le secret précédent, s’il existe. Sinon, s0 est vide.
Acceptez le webhook si votre signature correspond à s1, ou à s0 pendant une rotation du secret. Utilisez une fonction de comparaison à temps constant lorsque votre langage en propose une.
Lors d’une rotation du secret (depuis le tableau de bord HUB2), le secret précédent est conservé et sert à calculer s0 jusqu’à la rotation suivante. Vous pouvez ainsi passer au nouveau secret sans rejeter aucun webhook.