How to Test Braintree Webhooks

If you are using Braintree to handle subscriptions, disputes, or sub-merchant onboarding, webhooks are essential. Because many payment events occur asynchronously (like a monthly subscription billing successfully), Braintree uses webhooks to inform your server when these events take place.

However, Braintree's webhook architecture is older and significantly different from modern JSON-based APIs like Stripe or Square. Testing them requires a specific approach.

The Braintree payload format

When Braintree fires a webhook, they do not send a standard JSON body. Instead, they send an HTTP POST request formatted as application/x-www-form-urlencoded.

The body contains exactly two parameters: bt_signature and bt_payload.

The bt_payload is an XML string that has been base64-encoded. You cannot read this data just by logging the HTTP request to your terminal; you must actively decode and parse the XML to see the event details. This makes debugging incredibly tedious if you do not have the right tools in place.

Capturing and decoding payloads

Before writing the complex logic to decode and parse the XML payload, you should capture a real event to see what data Braintree provides.

Using a dedicated webhook inspector like Payloader removes the friction of manual decoding:

1. Create an endpoint URL in Payloader.
2. Log in to your Braintree Control Panel, go to Settings > Webhooks, and create a new webhook pointing to the Payloader URL.
3. Select the notifications you want to receive, such as "Subscription Charged Successfully".
4. Click "Check URL" to have Braintree fire a test event.

When the request hits Payloader, its intelligence engine automatically identifies the Braintree format. Payloader natively decodes the bt_payload, parses the underlying XML, and displays a human-readable summary of the event (e.g., highlighting the subscription ID and the transaction amount). You get immediate visibility into the data structure without writing a single line of base64 decoding logic.

Testing on localhost

To write your application logic, Braintree requires that your server parse the payload using their official Server SDK. Braintree SDKs include a webhookNotification.parse() method that handles the decoding and signature verification automatically.

But to pass the data to that SDK method, you need the webhook delivered to your local machine.

Use Payloader to forward the incoming Braintree webhooks directly to your local development environment. By proxying the traffic, you avoid the hassle of managing rotating ngrok URLs.

If your SDK throws an exception because you passed the parameters incorrectly, you do not need to trigger another event from the Braintree Control Panel. Just click "Replay" in Payloader, and it will immediately fire the exact same encoded form data back to your local server.

Security and signature verification

Braintree handles security differently than most platforms. Instead of relying on an HTTP header, the signature is passed directly in the request body as the bt_signature parameter.

This signature actually contains a pair of values: your public key and an HMAC-SHA1 hash of the payload generated using your private key.

You should rarely attempt to verify this signature manually. The official Braintree SDK handles this verification implicitly when you call the parse method. If the signature is invalid, the SDK will throw an exception, ensuring your application only processes authentic payment events.