Integration

Follow these steps to integrate webhooks:

Create an HTTP endpoint to receive webhook requests.

This endpoint must accept POST requests such as the one below:

URL: https://website.com/webhook_payment (HTTPS is mandatory)
METHOD: POST
HEADERS:

Content-Type: application/json
Hub2-Signature: s1=XXXXXX,s0=XXXXXX

BODY:

Click to show.

{
	"owner": "1234",
	"type": "payment_intent.created",
	"data": {
		"id": "pi_Doc5b1e7f0c93a24d68e1",
		"createdAt": "2021-03-03T11:16:39.280Z",
		"updatedAt": "2021-03-03T11:16:39.288Z",
		"merchantId": "1234",
		"purchaseReference": "ref_2020_11_10_001",
		"customerReference": "cust_01924059",
		"amount": 100,
		"currency": "XOF",
		"token": "eyJhbGciOiJIUzI1NiJ9.e30.fake-token-for-documentation",
		"status": "payment_required",
		"payments": [],
		"mode": "sandbox"
	},
	"test": false,
	"id": "evt_Doc8c4f2a91d07e3b56f2",
	"createdAt": "2021-03-03T11:16:39.685Z"
}

This is an example of a webhook sent for a payment_intent.created event. The data field holds the object concerned by the event, owner is your merchant ID and id identifies the event.

The HUB2 API provides a dedicated endpoint for this action. Call it with the following body:

Click to show.

{
	"url": "https://website.com/webhook_payment",
	"events": [
		"payment.created",
		"payment_intent.created"
	],
	"description": "Webhook triggered on payment and payment intent creation",
	"metadata": {}
}

Code samples:

curl -X POST \
	-H "Content-Type: application/json" \
	-H "ApiKey: YOUR_API_KEY" \
	-H "MerchantId: YOUR_MERCHANT_ID" \
	-H "Environment: sandbox" \
	-d '{ "url": "https://my.webhook.target", "events": ["payment.created", "payment_intent.created"], "description": "Webhook triggered on payment and payment intent creation", "metadata": {} }' \
https://api.hub2.io/webhooks

import fetch from 'node-fetch';

async function createWebhook() {
		const response = await fetch('https://api.hub2.io/webhooks', {
				method: 'POST',
				headers: {
						'Content-Type': 'application/json',
						'ApiKey': 'YOUR_API_KEY',
						'MerchantId': 'YOUR_MERCHANT_ID',
						'Environment': 'sandbox', // or 'live'
				},
				body: JSON.stringify({
						url: 'https://my.webhook.target',
						events: ['payment.created', 'payment_intent.created'],
						description: 'Webhook triggered on payment and payment intent creation',
						metadata: {},
				}),
		});

		if (response.ok) {
				const result = await response.json();
				console.log(result);
		} else {
				console.log(`HTTP Status: ${response.status}`);
		}
}

createWebhook();

import requests

url = 'https://api.hub2.io/webhooks'

headers = {
		'Content-Type': 'application/json',
		'ApiKey': 'YOUR_API_KEY',
		'MerchantId': 'YOUR_MERCHANT_ID',
		'Environment': 'sandbox',  # or 'live'
}

data = {
		'url': 'https://my.webhook.target',
		'events': ['payment.created', 'payment_intent.created'],
		'description': 'Webhook triggered on payment and payment intent creation',
		'metadata': {},
}

response = requests.post(url, headers=headers, json=data)

if response.ok:
		print(response.json())
else:
		print(f'HTTP Status: {response.status_code}')

The webhook is created in the environment (live or sandbox) given in the Environment header. The HUB2 API responds with HTTP 201 and a body such as:

Click to show.

{
	"id": "wh_Doc3e9a6d14f2b07c85a9",
	"createdAt": "2020-10-15T12:09:49.355Z",
	"updatedAt": "2020-10-15T12:09:49.355Z",
	"mode": "sandbox",
	"description": "Webhook triggered on payment and payment intent creation",
	"events": ["payment.created", "payment_intent.created"],
	"metadata": {},
	"secret": "whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"status": "enabled",
	"url": "https://my.webhook.target"
}

This response contains the secret associated with the webhook: "secret": "whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX". It is returned only once, at creation.

Store the secret securely: you need it to verify the integrity of every webhook you receive.For more details, see the webhooks API reference: Create a webhook.

Verify the webhook signature.

This step is mandatory: it ensures that no one can send you forged webhooks.Skipping it leaves a vulnerability that a malicious party could exploit, for example to have their own transactions validated.

To make sure a webhook comes from the HUB2 API, check the signature of its body (payload).

a. Get the secret of the webhook.

This secret was returned in step 2 ("secret": "whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" in the example).

b. Sign the payload.

Take the body of the POST request sent by HUB2 (see step 1) as a string, exactly as received, and compute its HMAC-SHA256 with the secret as key, encoded in lowercase hexadecimal.Examples by programming language:

// Example with Node.js
import { createHmac } from 'crypto';

function sign(rawBody, secret) {
	return createHmac('sha256', secret).update(rawBody).digest('hex');
}

# Example with Python
import hashlib
import hmac

def sign(raw_body, secret):
	return hmac.new(secret.encode('utf-8'), raw_body.encode('utf-8'), hashlib.sha256).hexdigest()

// Example with Java 17+
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.GeneralSecurityException;
import java.util.HexFormat;

public String sign(String rawBody, String secret) {
	try {
		Mac mac = Mac.getInstance("HmacSHA256");
		mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
		byte[] hmacBytes = mac.doFinal(rawBody.getBytes(StandardCharsets.UTF_8));
		return HexFormat.of().formatHex(hmacBytes);
	} catch (GeneralSecurityException e) {
		throw new IllegalStateException(e);
	}
}

# Example with Ruby
require 'openssl'

def sign(raw_body, secret)
	OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret, raw_body)
end

// Example with C#
using System;
using System.Security.Cryptography;
using System.Text;

public string Sign(string rawBody, string secret)
{
	using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
	{
		byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawBody));
		return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
	}
}

// Example with PHP
function sign($rawBody, $secret) {
	return hash_hmac('sha256', $rawBody, $secret);
}

Sign the raw body as received, before any parsing. Parsing the JSON and serializing it again can change the string (spacing, key order, character escaping) and produce a different signature.

c. Check the signature.

Finally, compare the computed signature with the one sent by HUB2 in the request headers:

Hub2-Signature: s1=ABCD,s0=XYZ

Hub2-Signature: header name (HTTP header names are case-insensitive).
s1: signature computed with the current secret.
s0: signature computed with the previous secret, if there is one. Otherwise, s0 is empty.

Accept the webhook if your signature matches s1, or s0 during a secret rotation. Use a constant-time comparison function where your language provides one.

When the secret is rotated (from the HUB2 dashboard), the previous secret is kept and used to compute s0 until the next rotation. This lets you switch to the new secret without rejecting any webhook.

Getting started

Transfers

Payments

Webhooks

Processing Only

Payment Links

Submerchants

Other

a. Get the secret of the webhook.

b. Sign the payload.

c. Check the signature.

​a. Get the secret of the webhook.

​b. Sign the payload.

​c. Check the signature.

a. Get the secret of the webhook.

b. Sign the payload.

c. Check the signature.