Here are the steps to follow for a proper integration of webhooks :

1

Create a callback HTTP endpoint to receive webhooks requests.

This endpoint must be able to process a POST request as below:

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

This is an example of webhook issued by a payment_intent.created event.

2

Call HUB2 API to register this endpoint and subscribe to a webhook event.

The HUB2 API does have a dedicated endpoint for this action. It must be called with the following body:

Here are samples of code to perform this:

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

This is a sample of the HUB2 API response to this call:

This response contains a secret associated with the created webhook: "secret": "5257a869e7ecebeda32affa62cd...".

The secret must be kept carefully. It will be mandatory to verify the integrity of the webhook.

For more details on the webhooks API, check the following documentation: Webhooks API Documentation

3

Webhook signature verification.

This step is mandatory to ensure that no one can forge fake webhooks.

Skipping this step may offer a vulnerability to harmful people, allowing them to automatically validate transactions themselves.

To ensure the webhook received comes from the HUB2 API, it is imperative to check the signature of the body (payload).

​
a. Get the secret from the webhook registration.

This secret was generated in step 2, "secret": "5257a869e7ecebeda32affa62cd..." in our example.

​
b. Sign the payload.

Extract the contents of the BODY from the POST request sent by Hub2 first (see Json response). It should result in a characters string that must be signed via HMAC256 and the secret.

Here are some examples of procedures depending on the programming language used :

// 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');
}

The request body must be in JSON string. Either the framework used directly returns a JSON string or it must be transformed to JSON format with a call like JSON.stringify() on the body of the request.

​
c. Check signature.

Finally, the computed signature must be compared to the one provided by HUB2, located in the HEADERS of the POST request.

Hub2-Signature: s1=ABCD,s0=XYZ
  • Hub2-Signature: Header name
  • s1: Signature computed using current secret.
  • s0: Signature computed using old secret oldSecretif present.

When updating a secret, the previous active secret becomes oldSecret for a period of 24 hours and is used to generate the s0 signature.