HMAC Signatures

To protect your integration server from unauthorized webhook events, each webhook will include an HMAC signature (x-hmac-signature). This signature is derived from a secret HMAC key and the webhook payload. By verifying this HMAC signature, you can confirm that the webhook was sent by Hellgate® and that it has not been modified or tampered with during transmission.

HMAC Key

The HMAC key is randomly generated when you create a webhook and consists of a 64-character string that includes digits (1-9) and uppercase letters (A-Z).

HMAC Signature

The x-hmac-signature is a base16-encoded (hex) Message Authentication Code (MAC) generated from the payload.

Verify HMAC Signatures

To verify the validity of the HMAC signature, follow these steps:

1. Calculate the HMAC using:

• The payload you received in the webhook
• The HMAC key
• The SHA256 hashing function

2. Compare the calculated HMAC with the x-hmac-signature you received.

If the calculated HMAC matches the x-hmac-signature, you can be confident that the webhook event was sent by Hellgate® and has not been altered during transmission.

Example

Example HMAC Key:

APJ29CF5LPFXC189YPJT2HX92P0HKVINX63N4TE4WOCUYBT3LKBAQIF25I423DCA

Example Payload:

{
  "id": "6a757512-44e8-44cd-ad82-f7e9da2f353a",
  "created_at": "2024-08-09T09:08:20.809661Z",
  "event_type": "token.created",
  "token": {
    "account_number_last_four": "3490",
    "account_number_length": 16,
    "authentication_data": {},
    "bank_name": "Intl Hdqtrs-Center Owned",
    "card_art_url": null,
    "cardholder_name": "John Doe",
    "country_code": "US",
    "created_at": "2024-08-09T09:08:20.798263Z",
    "expires_at": null,
    "expiry_month": 12,
    "expiry_year": 2025,
    "id": "6a757512-44e8-44cd-ad82-f7e9da2f353a",
    "identity_and_verification": "none",
    "invalidated_at": null,
    "issuer_identification_number": "46229431",
    "masked_account_number": "462294XXXXXX3490",
    "network_token_status": "pending",
    "scheme": "VISA",
    "segment": "consumer",
    "status": "active",
    "supports_device_binding": false,
    "type": "debit"
  }
}

x-hmac-signature received in the Webhook:

7d2a6ac096d31e4b27c2efc44c0966498007b4aeffdfbb54da55d258911dbaf5

Develop your custom solution to verify HMAC signatures:

const crypto = require('crypto');

function sign(payload, hmacKey) {
  // Convert payload and key to Buffer objects (binary data)
  const payloadBuffer = Buffer.from(payload, 'utf-8');
  const keyBuffer = Buffer.from(hmacKey, 'utf-8');

  // Create an HMAC using the SHA-256 algorithm
  const hmac = crypto.createHmac('sha256', keyBuffer);

  // Update the HMAC with the payload
  hmac.update(payloadBuffer);

  // Compute the HMAC digest and encode it as a hexadecimal string
  return hmac.digest('hex');
}

// Example usage:
const payload =
  '{"id":"3be16244-9b33-476d-9cd1-24c6975d2faa","created_at":"2024-08-09T13:40:20.211171Z","event_type":"token.updated","token":{"account_number_last_four":"5000","account_number_length":16,"authentication_data":{"acs_transaction_id":"ff7d353e-9d97-45ff-b5c4-175a5a7a5c85","transaction_status":"Y","transaction_status_reason":null},"bank_name":"SF* Demo Bank","card_art_url":null,"cardholder_name":"John","country_code":"DE","created_at":"2024-08-09T13:40:19.669423Z","expires_at":null,"expiry_month":8,"expiry_year":2025,"id":"3be16244-9b33-476d-9cd1-24c6975d2faa","identity_and_verification": "none","invalidated_at":null,"issuer_identification_number":"41000000","masked_account_number":"410000XXXXXX5000","network_token_status":"failed","scheme":"VISA","segment":"consumer","status":"active","supports_device_binding":false,"type":"credit"}}';
const hmacKey = 'APJ29CF5LPFXC189YPJT2HX92P0HKVINX63N4TE4WOCUYBT3LKBAQIF25I423DCA';
const signature = sign(payload, hmacKey);
console.log(signature);

The output of this code example will be the HMAC signature:

7d2a6ac096d31e4b27c2efc44c0966498007b4aeffdfbb54da55d258911dbaf5

By comparing the x-hmac-signature with the calculated signature, you can confirm that the webhook sent by Hellgate® is legitimate.