Braintree webhooks
Last verified against Braintree's documentation on September 27, 2026.
Braintree sends webhooks when something happens to a subscription, a transaction, a dispute, or a merchant account. Its notifications look different from most: a form-encoded POST with two fields, bt_signature and bt_payload, that Braintree’s SDK verifies and decodes for you. Braintree retries hourly for up to 24 hours in production. This page covers what Braintree sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What Braintree sends webhooks for
| Area | Example kinds | Typical use |
|---|---|---|
| Subscriptions | subscription_charged_successfully, subscription_charged_unsuccessfully, subscription_went_past_due, subscription_canceled | Keep access and billing in sync |
| Transactions | transaction_settled, transaction_settlement_declined, transaction_disbursed | Track settlement |
| Disputes | dispute_opened, dispute_won, dispute_lost | Respond to disputes |
| Test | check | Confirm your endpoint works |
The SDK’s parse method returns a notification with a kind, a timestamp, and the related Braintree object, such as a subscription or transaction, as it was when the webhook fired.
How Braintree delivers webhooks
| Behavior | Detail |
|---|---|
| Method and format | POST with application/x-www-form-urlencoded fields bt_signature and bt_payload |
| Verification | The SDK’s parse method checks bt_signature against bt_payload with your API keys and decodes the payload |
| Timeout | 30 seconds |
| Success | Any 2xx within 30 seconds |
| Retries | Hourly for up to 24 hours in production, and up to 3 hours in sandbox |
| Ordering | Not guaranteed. Use the notification’s timestamp |
Common Braintree webhook errors and how to fix them
Invalid signature exception
- Body not parsed as a form. The fields arrive form-encoded. Make sure your framework parses
application/x-www-form-urlencodedon this route. - Wrong gateway credentials. Parse with the same environment’s merchant ID and keys that the webhook belongs to. Sandbox and production are separate.
req.body is undefined
A JSON-only body parser skips form-encoded requests. Add a URL-encoded parser for the webhook route.
Timeouts cause repeats
A handler that takes over 30 seconds is treated as failed and retried an hour later. Respond first, then process.
Stale state applied
Notifications aren’t sent in order, and each carries the object as it was at that moment. Compare the timestamp with what you’ve stored, or fetch the object from the API.
Why use HookDeploy with Braintree
Capture every notification
HookDeploy captures every Braintree webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. If your server is down for longer than Braintree’s 24 hours of retries, notifications are still in HookDeploy.
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
- History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.
One webhook, many systems
Send each Braintree event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Deliver to systems Braintree can’t reach
The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive Braintree events with no public endpoint.
Develop against real events
A tap sends a temporary copy of live Braintree events to 127.0.0.1 on your machine while production keeps receiving them.
Know the limits
- Transformations. A transformation changes the form body, and then the signature won’t verify at that destination.
- Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Braintree treats as a failed delivery. Paid plans keep accepting traffic past the included volume.
Retries, replays, and duplicates
Braintree’s signature travels in the body, in the bt_signature field, and HookDeploy forwards the body unchanged, so retries and replays verify like the original delivery. A privacy filter that changes the stored copy used for retries and replays breaks it.
Braintree’s retries, HookDeploy’s retries, and replays can all deliver the same notification. Deduplicate on the object’s ID together with the kind and timestamp.
Set up Braintree with HookDeploy
- In HookDeploy, create an endpoint (for example,
Braintree production) and copy its URL. - On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
- In the Braintree Control Panel, go to Settings, then Webhooks, and create a new webhook with your HookDeploy URL and the notification kinds you want.
- Use Check URL on the webhook, which sends a
checknotification, and confirm it appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import express from 'express';
import braintree from 'braintree';
const app = express();
const gateway = new braintree.BraintreeGateway({
environment: braintree.Environment.Production,
merchantId: process.env.BT_MERCHANT_ID,
publicKey: process.env.BT_PUBLIC_KEY,
privateKey: process.env.BT_PRIVATE_KEY,
});
app.post('/webhooks/braintree', express.urlencoded({ extended: false }), async (req, res) => {
let notification;
try {
notification = await gateway.webhookNotification.parse(req.body.bt_signature, req.body.bt_payload);
} catch {
return res.status(401).send('Invalid signature');
}
res.sendStatus(200);
if (notification.kind === 'check') return;
await enqueue({ kind: notification.kind, timestamp: notification.timestamp, subject: notification.subject });
// Deduplicate on the object ID, kind, and timestamp in your worker.
});
FAQ
How do I verify a Braintree webhook?
Pass the bt_signature and bt_payload form fields to your SDK's webhook notification parse method, using the same environment's credentials. It verifies the signature, decodes the payload, and raises an invalid signature error if they don't match.
Why is req.body empty for Braintree webhooks?
Braintree sends form-encoded data, not JSON. Add a URL-encoded body parser to the webhook route.
How long does Braintree retry webhooks?
Braintree retries hourly for up to 24 hours in production, and up to 3 hours in sandbox, until it gets a 2xx within 30 seconds.
What is the check webhook?
A test notification Braintree sends when you use Check URL on a webhook in the Control Panel, to confirm your endpoint responds.
Are Braintree webhooks sent in order?
No. Use each notification's timestamp, and fetch the object from the API when you need its current state.
Does HookDeploy break Braintree signature verification?
No. The signature is in the form body, and HookDeploy forwards the body unchanged, so first deliveries, retries, and replays all verify.