Webhooks

Payload Signing

Every webhook request we send includes two headers to help you verify the payload comes from the bank:

• X-Braid-SecurityDigest – This is our HMAC-SHA256 hash using the secret key you received when creating the webhook. We hash the timestamp and the body together.
• X-Braid-OriginalTransmissionTime – This is the timestamp (in milliseconds, epoch format) when we originally sent the webhook. It doesn’t change if the webhook is retried.

To verify the webhook:

1. Take the X-Braid-OriginalTransmissionTimevalue.
2. Append the raw JSON body.
3. Run an HMAC-SHA256 hash using your webhook secret key.
4. Compare the result to the X-Braid-SecurityDigest.

Example

// Inputs from the incoming request
String receivedDigest = request.getHeader("X-Braid-SecurityDigest");
String originalTimestamp = request.getHeader("X-Braid-OriginalTransmissionTime");
String requestBody = getRawRequestBody(request);

// The secret key you received when creating the webhook
String secretKey = "your-secret-key";

// Create the payload string to hash
String payloadToHash = originalTimestamp + requestBody;

// Compute your own HMAC-SHA256 hash
String expectedDigest = computeHmacSha256(payloadToHash, secretKey);

// Compare your digest with the one we sent
if (!expectedDigest.equals(receivedDigest)) 
{
    throw new SecurityException("Suspicious webhook detected – signature mismatch");
}

This check ensures the payload came from us and wasn’t tampered with. Always run it before trusting the data.