Secure your webhooks

Once you've set up your server and exposed it to the internet, it will receive any payloads that are sent to it. To improve security, you should:

1. Limit requests to your server to those coming from Mambo servers
2. Verify the signature sent with each request from Mambo

The signature is created using the secret key specified when you set up your webhook. Make sure to use a secure key with high entropy. To verify the signature sent with each request, the key will also need to be available on your server. Don't hardcode the key into your application; instead, use best practices for key management.

Preventing replay attacks

To mitigate the risk of replay attacks, a timestamp is included in the X-Mambo-Signature header. The timestamp is part of the signature, which means an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, your application can reject the request.

Note that each time Mambo attempts a webhook delivery, a new timestamp and signature is generated. So any time a delivery attempt fails and is retried or a manual retry is attempted, we will generate a new timestamp and signature.

Ensure your server's clock is accurate and uses Network Time Protocol (NTP) so that it aligns with Mambo's servers.

Validating the request signature

Each webhook request sent to your servers will contain the X-Mambo-Signature header. This header contains a timestamp and a hash signature (HMAC SHA-256) of the timestamp concatenated with the payload created using the secret key.

To verify the signature, you will calculate the hash locally using your secret key and compare it to the hash signature sent in the webhook request's header. The hash signature is computed using the HMAC SHA256 hex digest algorithm and applying it to the timestamp concatenated with the payload. Below is an example of the X-Mambo-Signature header:

HTTP

X-Mambo-Signature: t=1640353547371,
v1=2c1ca596cfabeaeac76c425bed5c3b3c788445442f4d4d24cb4f13a937212621

The steps below explain how to validate the signature:

1. Extract the timestamp and signature from the header: split the header using the , (comma) character to get a list containing the timestamp and the signature. Then split each element in the list using the = (equals) character to get a key/value pair. The value for the key t is the timestamp and the value for the key v1 is the signature.

2. Prepare the payload string for hashing: create the string that will be given to the hashing function by concatenating the timestamp retrieved in the header and the payload (the request body). Simply join the two strings together (i.e. timestamp + payload).

3. Compute the signature: create an HMAC SHA256 hash. Use the string we prepared in the previous step together with the webhook's signing secret.

4. Compare the signatures: compare the signature in the header with the signature computed in the previous step. To prevent timing attacks, use a constant-time string comparison to compare the two signatures.

5. Verify the timestamp: once the signatures are validated, you can verify the timestamp in the header to check if it is within your time tolerance.

The code sample below illustrates how this can be done in Java:

Java

.NET

PHP

public boolean isValidSignature( String signatureHeader, String payload, String secret ) {
  String signature = computeSignature( signatureHeader, payload, secret );
  return MessageDigest.isEqual( signatureHeader.getBytes(), signature.getBytes() );
}

private String computeSignature( String signatureHeader, String payload, String secret ) {
  String timestamp = extractTimestamp( signatureHeader );
  byte[] key = secret.getBytes();
  HmacUtils hmac256 = new HmacUtils( HmacAlgorithms.HMAC_SHA_256, key );
  return hmac256.hmacHex( timestamp + payload );
}

private String extractTimestamp( String signatureHeader ) {
  String timestamp = signatureHeader.split( "," )[0];
  return timestamp.split( "=" )[1];
}

public bool IsValidSignature(string signatureHeader, string payload, string secret)
{
  string signature = ComputeSignature(signatureHeader, payload, secret);
  return CryptographicOperations.FixedTimeEquals(
      Convert.FromHexString(signatureHeader),
      Convert.FromHexString(signature));
}

private string ComputeSignature(string signatureHeader, string payload, string secret)
{
  string timestamp = ExtractTimestamp(signatureHeader);
  byte[] key = Encoding.UTF8.GetBytes(secret);
  using var hmac = new HMACSHA256(key);
  byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(timestamp + payload));
  return Convert.ToHexString(hash).ToLower();
}

private string ExtractTimestamp(string signatureHeader)
{
  string timestamp = signatureHeader.Split(',')[0];
  return timestamp.Split('=')[1];
}

function isValidSignature(string $signatureHeader, string $payload, string $secret): bool
{
 $signature = computeSignature($signatureHeader, $payload, $secret);
 return hash_equals($signatureHeader, $signature);
}

function computeSignature(string $signatureHeader, string $payload, string $secret): string
{
  $timestamp = extractTimestamp($signatureHeader);
  $hash = hash_hmac('sha256', $timestamp . $payload, $secret);
  return $hash;
}

function extractTimestamp(string $signatureHeader): string
{
 $timestamp = explode(',', $signatureHeader)[0];
 return explode('=', $timestamp)[1];
}

There are a number of important factors to consider when implementing this code in your preferred language:

• Use a constant time string comparison to verify the signature in order to avoid timing attacks. Most languages today provide string comparison methods which use constant time comparison. Note that the MessageDigest class in Java was vulnerable to timing attacks prior to version SE 6u17.
• Make sure you handle the payload using UTF-8 character encoding as it may contain unicode characters.