Verify HMAC signatures for Drive API webhooks using current and next secrets to secure session events and CDR forwarding. To ensure secure communication between our Drive API and your backend, we sign all webhook requests using HMAC (Hash-based Message Authentication Code). This guide explains how to verify the HMAC signature on your end to confirm the authenticity and integrity of the received requests. This applies to our different webhooks: Session Events: Documentation CDRs (Charging Detail Records)

HMAC Secret Keys

To enable HMAC, please reach out to us. We will enable it and securely send you two secret keys:

CURRENT: The active secret used to sign webhook messages.
NEXT: The upcoming secret that will replace CURRENT if a secret key rotation should happen.

Your system should always try to verify the signature with CURRENT and fallback to NEXT. This ensures a smooth transition if we have to rotate secrets, preventing disruptions in webhook processing. More explanation on the key rotation process below.

Verifying the HMAC Signature

Each webhook request includes the X-HMAC-SHA512-Signature header, which contains the base64-encoded HMAC signature of the request’s payload. To verify the signature:

Retrieve the Signature and Payload
- Extract X-HMAC-SHA512-Signature from the request headers.
- Extract the raw request body (as a string).
Compute and verify the signature with the CURRENT secret key
- Compute an HMAC signature of the request body using SHA-512 and the CURRENT secret key.
- Convert the computed signature to a base64-encoded string.
- Compare it with the received X-HMAC-SHA512-Signature header. If they match, the request is valid. If not, compute the HMAC signature with the NEXT secret key. If it still doesn’t match, the request should be rejected.

Sample implementation

Javascript

import * as crypto from 'crypto';

const ALGORITHM = 'sha512';
const SIGNATURE_HEADER_NAME = 'X-HMAC-SHA512-Signature';

function verifyHmacSignature(headers, body, currentSecret, nextSecret) {
  const receivedSignature = headers[SIGNATURE_HEADER_NAME];
  if (!receivedSignature) {
    throw new Error('Missing HMAC signature header');
  }

  const isValid = [currentSecret, nextSecret].some(secret => {
    const computedSignature = sign(secret, body);
    return crypto.timingSafeEqual(
      Buffer.from(receivedSignature, 'base64'),
      Buffer.from(computedSignature, 'base64')
    );
  });

  return isValid;
}

function sign(hmacSecret, body) {
  const secretKeyBytes = Buffer.from(hmacSecret, 'base64');
  const hmac = crypto.createHmac(ALGORITHM, secretKeyBytes);
  hmac.update(body);
  return hmac.digest('base64');
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class HmacSignatureVerifier {
    private static final String HMAC_ALGORITHM = "HmacSHA512";
    private static final String SIGNATURE_HEADER_NAME = "X-HMAC-SHA512-Signature";

    public static boolean verifyHmacSignature(String receivedSignature, String requestBody, String currentSecret, String nextSecret) {
        if (receivedSignature == null || receivedSignature.isEmpty()) {
            throw new IllegalArgumentException("Missing HMAC signature header");
        }

        return receivedSignature.equals(computeHmac(currentSecret, requestBody)) ||
               receivedSignature.equals(computeHmac(nextSecret, requestBody));
    }

    private static String computeHmac(String secret, String data) {
        try {
            byte[] secretBytes = Base64.getDecoder().decode(secret);
            Mac mac = Mac.getInstance(HMAC_ALGORITHM);
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretBytes, HMAC_ALGORITHM);
            mac.init(secretKeySpec);
            byte[] hmacBytes = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
            return Base64.getEncoder().encodeToString(hmacBytes);
        } catch (Exception e) {
            throw new RuntimeException("Error computing HMAC", e);
        }
    }
}

Key Rotation Process

Here is the process for rotating keys:

On our side we sign the payload with NEXT instead of CURRENT. Your system continues working since you verify with both secrets.
We generate a new NEXT secret and securely send it to you. CURRENT takes the value of NEXT and NEXT gets the new value you received from us.

Guides

API reference

Verifying HMAC signature

HMAC Secret Keys

Verifying the HMAC Signature

Sample implementation

Javascript

Java

Key Rotation Process

​HMAC Secret Keys

​Verifying the HMAC Signature

​Sample implementation

​Javascript

​Java

​Key Rotation Process

HMAC Secret Keys

Verifying the HMAC Signature

Sample implementation

Javascript

Java

Key Rotation Process