Skip to content
HookDeploy

Braintree webhooks

Last verified against Braintree's documentation on September 27, 2026.

On this page ↓

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

AreaExample kindsTypical use
Subscriptionssubscription_charged_successfully, subscription_charged_unsuccessfully, subscription_went_past_due, subscription_canceledKeep access and billing in sync
Transactionstransaction_settled, transaction_settlement_declined, transaction_disbursedTrack settlement
Disputesdispute_opened, dispute_won, dispute_lostRespond to disputes
TestcheckConfirm 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

BehaviorDetail
Method and formatPOST with application/x-www-form-urlencoded fields bt_signature and bt_payload
VerificationThe SDK’s parse method checks bt_signature against bt_payload with your API keys and decodes the payload
Timeout30 seconds
SuccessAny 2xx within 30 seconds
RetriesHourly for up to 24 hours in production, and up to 3 hours in sandbox
OrderingNot 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-urlencoded on 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

  1. In HookDeploy, create an endpoint (for example, Braintree production) and copy its URL.
  2. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  3. 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.
  4. Use Check URL on the webhook, which sends a check notification, 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.

Capture Braintree webhooks free

Start free