Voici les étapes à suivre pour une intégration correcte des webhooks :

1

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

Ce point de terminaison doit être capable de traiter les requêtes POST telle que ci-dessous:

  • URL: https://website.com/webhook_payment
  • METHOD: POST
  • HEADERS:
ContentType: application/json
Hub2-Signature: s1=XXXXXX,s0=XXXXXX
  • BODY:

C’est un exemple de webhook retourné en cas d’événement payment_intent.created.

2

Référencer ce point de terminaison dans l'API HUB2 et le souscrire à un événement.

L’API HUB2 a un point de terminaison dédié à cette action qui doit être appelé avec le contenu suivant :

Voici des exemples de code pour faire ainsi :

curl -X POST \
	-H "Content-Type: application/json" \
	-H "ApiKey: Your API KEY" \
	-H "MerchantId: Your merchant Id" \
	-H "Environment: Your API KEY environment 'live' or 'sandbox'" \
	-d '{ "url": "https://my.webhook.target", "events": ["payment.created", "payment_intent.created"], "description": "This is a webhook trigger upon payment & payment_intent creation", "metadata": {} }' \
https://api.hub2.io/webhooks

Voici un exemple de réponse de l’API HUB2 à cet appel :

Cette réponse contient un secret associé au webhook créé: "secret": "5257a869e7ecebeda32affa62cd...".

Ce secret doit être gardé précieusement, il sera nécessaire pour vérifier l’intégrité du webhook reçu.

Pour plus de détails sur l’API Webhooks, consulter la documentation suivante :: Documentation API Webhooks

3

Vérification de la signature du webhook.

Cette étape est nécessaire pour s’assurer que personne ne peut forger de faux webhooks.

Passer cette étape laisse une vulnérabilité pour des personnes malicieuses qui pourront valider leurs transactions eux-mêmes.

Afin de s’assurer que le webhook reçu provient bien de l’API HUB2, il est impératif de verifier la signature du body (payload).

​
a. Se prémunir du secret associé au webhook.

Ce secret a été généré à l’étape 2 ("secret": "5257a869e7ecebeda32affa62cd..." dans notre exemple).

​
b. Signer le payload.

Extraire le contenu du BODY de la requête POST envoyée par Hub2 (voir Json response). Il en résulte une chaîne de caractères qui doit être signée via HMAC256 et le secret.

Voici quelques exemples de procédure selon le langage de programmation utilisé :

// Example with Javascript/NestJS
import { createHmac, Hmac } from 'crypto';

sign(json: string, secret: string): string {
	const hmac: Hmac = createHmac('sha256', secret);
	hmac.update(json);
	return hmac.digest('hex');
}

Le corps de la requête doit être une string JSON. Soit le framework web utilisé retourne directement du JSON, soit il faut faire un appel type JSON.stringify() sur le corps de votre requête pour l’obtenir.

​
c. Vérifier la signature.

Pour finir il faut comparer la signature calculée à celle fournie par Hub2. La signature se situe dans les HEADERS de la requête.

Hub2-Signature: s1=ABCD,s0=XYZ
  • Hub2-Signature: Nom du header
  • s1: Correspond à la signature faite avec le secret actif.
  • s0: Correspond à la signature faite avec un ancien oldSecret si présent.

Lors d’une mis à jour d’un secret, le précédent secret actif devient oldSecret pendant une durée de 24h et est utilisé pour générer la signature s0.