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 la charge utile.

Lisez t, le timestamp Unix en secondes, dans l’en-tête Hub2-Signature-V2 (voir l’étape c). 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 le HMAC-SHA256 de la chaîne <t>.<corps brut> 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-V2 : nom de l’en-tête (les noms d’en-têtes HTTP ne sont pas sensibles à la casse).
  • t : timestamp Unix en secondes, celui que vous avez signé à l’étape b.
  • v1 : signature calculée avec le secret actuel.
  • v0 : signature calculée avec le secret précédent pendant les 24 heures qui suivent une rotation. Sinon, v0 est omis.
Acceptez le webhook uniquement si t ne s’écarte pas de plus de 5 minutes de votre heure actuelle et si votre signature correspond à v1, ou à v0 pendant une rotation du secret. Utilisez une fonction de comparaison à temps constant lorsque votre langage en propose une. Les nouvelles tentatives et les rejeux portent un nouveau t, mais le même id d’événement : dédoublonnez sur l’id.
Chaque requête contient aussi l’ancien en-tête Hub2-Signature: s1=<signature>,s0=<signature>, où s1 et s0 sont le HMAC-SHA256 du seul corps brut, avec le secret actuel et le secret précédent (s0 est vide hors rotation). Il est conservé pour les intégrations existantes, mais il ne comporte pas de timestamp et ne protège pas contre le rejeu de requêtes : utilisez Hub2-Signature-V2.
Lors d’une rotation du secret (depuis le tableau de bord HUB2), le secret précédent continue de signer les envois (v0, et s0 dans l’ancien en-tête Hub2-Signature) pendant 24 heures. Ensuite, seul le nouveau secret est utilisé. Passez votre point de terminaison au nouveau secret dans ce délai.