braintree · AsyncAPI Specification
Braintree Webhooks
Version 1.0
Braintree Webhooks deliver automated HTTP POST notifications to a merchant-configured destination URL when specific events occur within the payment gateway. Webhook notifications are triggered by transaction settlements, subscription lifecycle changes, dispute events, disbursements, sub-merchant account updates, and other gateway events. Each notification payload is sent as a form-encoded POST with a bt_signature field and a bt_payload field, where the payload is a Base64-encoded signed XML document. Merchants must verify the signature using their API keys before processing the payload. Webhooks are configured in the Braintree Control Panel by specifying a destination URL and selecting the event types to monitor.
Channels
/webhook
Receive a Braintree webhook notification
The merchant's webhook endpoint that receives HTTP POST notifications from Braintree. All event types are delivered to the same configured URL. The bt_payload contains a Base64-encoded, signed XML document with the event details. Merchants must verify the bt_signature against the payload using their private API key before processing.
Messages
SubscriptionChargedSuccessfully
Subscription Charged Successfully
A subscription billing cycle completed with a successful charge.
SubscriptionChargedUnsuccessfully
Subscription Charged Unsuccessfully
A subscription billing cycle charge attempt failed.
SubscriptionWentActive
Subscription Went Active
A subscription transitioned to Active status.
SubscriptionWentPastDue
Subscription Went Past Due
A subscription transitioned from Active to Past Due status.
SubscriptionExpired
Subscription Expired
A subscription reached its configured number of billing cycles.
SubscriptionCanceled
Subscription Canceled
A subscription was canceled.
SubscriptionTrialEnded
Subscription Trial Ended
A subscription's trial period ended.
SubscriptionBillingSkipped
Subscription Billing Skipped
A subscription billing cycle was skipped due to a zero or negative balance.
TransactionSettled
Transaction Settled
A transaction settled successfully.
TransactionSettlementDeclined
Transaction Settlement Declined
Settlement for a transaction was declined.
DisputeOpened
Dispute Opened
A new dispute was opened against a transaction.
DisputeWon
Dispute Won
A dispute was resolved in the merchant's favor.
DisputeLost
Dispute Lost
A dispute was resolved in the cardholder's favor.
DisputeAccepted
Dispute Accepted
A dispute was accepted by the merchant.
DisputeAutoAccepted
Dispute Auto-Accepted
A dispute was automatically accepted after the reply deadline passed.
DisputeDisputed
Dispute Disputed
Evidence was submitted and the dispute is under review.
DisputeExpired
Dispute Expired
A dispute expired without resolution.
DisputeUnderReview
Dispute Under Review
A dispute is under internal review with PayPal.
Disbursement
Disbursement
Funds were disbursed to the merchant's bank account.
TransactionDisbursed
Transaction Disbursed
A transaction was marked for disbursement. Deprecated in favor of the Disbursement event.
SubMerchantAccountApproved
Sub-Merchant Account Approved
A Braintree Marketplace sub-merchant account was approved.
SubMerchantAccountDeclined
Sub-Merchant Account Declined
A Braintree Marketplace sub-merchant account application was declined.
Servers
https
merchantServer
{webhookDestinationUrl}
The merchant-configured HTTPS endpoint that receives webhook notifications from Braintree. The URL is set in the Braintree Control Panel and must be publicly accessible.