Intégration

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:

{
	"type": "payment_intent.created",
	"data": {
		"id":"pi_9lEjld8yF2USvijl7mnId",
		"merchantId":"10",
		"createdAt":"2021-03-03T11:16:39.280Z",
		"updatedAt":"2021-03-03T11:16:39.288Z",
				"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoiMTAiLCJtb2RlIjoic2FuZGJveCIsInBheW1lbnRJZCI6InBpXzlsRWpsZDh5RjJVU3Zpamw3bW5JZCIsImlhdCI6MTYxNDc3MDE5OX0.fkak8HAfHvcCeCxtzBEx1bE39oWl4vkGNgWdhnAmhXo",
		"purchaseReference":"ref_2020_11_10_001",
		"customerReference":"cust_01924059",
		"status":"payment_required",
		"amount":100,
		"currency":"XOF",
		"payments":[],
		"mode":"sandbox"
	},
	"id": "evt_O80mmIF5CNrBMbZIyHJye",
	"createdAt": "2021-03-03 11:16:39.685+00"
}

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

{
	"url": "https://website.com/webhook_payment",
	"events": [
		"payment.created",
		"payment_intent.created",
	],
	"description": "This is a webhook trigger upon payment & payment_intent creation",
	"metadata": {}
}

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 :

{
	"id": "wh_z1urYtVFgEebtcj8fxp4v",
	"createdAt": "2020-10-15T12:09:49.355Z",
	"updatedAt": "2020-10-15T12:09:49.355Z",
	"mode": "live",
	"description": "This is a webhook trigger upon payment & payment_intent creation",
	"events": ["payment.created", "payment_intent.created"],
	"metadata": { },
	"secret": "5257a869e7ecebeda32affa62cd...",
	"status": "enabled",
	"url": "https://website.com/webhook_payment"
}

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

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.