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.

Webhook configuration

• Each environment supports a single active webhook configuration. Attempting to create a second one returns a 422 error ("You already have active webhook configuration, please update that one").
• A single configuration can subscribe to multiple event types, or to all events by setting includeAllEvents to true.
• To change your endpoint URL or which events you receive, update your existing configuration rather than creating a new one.
• If you need to deliver events to more than one destination, point the single configuration at one endpoint on your side and fan the events out from there.

Choosing which events to subscribe to

• For most integrations, subscribe to TRANSACTION_STATUS_UPDATE and treat it as a single, cross-rail source of truth for transaction status changes.
• Rail-specific events (for example, the ACH_ORIGINATION, WIRE, and ACH_INBOUND event families) remain available and are useful when you need individual rail milestones.

Note: an ACH_ORIGINATION_SENT event means the ACH was transmitted to the network, not that funds have settled or posted. For settlement, key off the transaction reaching a POSTED 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");
}

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.