Webhooks

You can subscribe to our webhooks to be notified of incoming transactions and status changes.

An important webhook to monitor is TRANSACTION_STATUS_UPDATE. This webhook notifies you whenever a transaction is posted. Use it to update the transaction’s Primary status as well as any Processing Status.

API Details

API for Webhook Subscription

List of Webhook Responses

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-OriginalTransmissionTime value.
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.

Responding to Webhooks

When you receive the webhook events, you can respond back with the following HTTP Status after the processing has been completed on your end.