Webhooks are a system of automated notifications indicating that an event has occurred in your gateway. Rather than requiring you to pull information via our API, webhooks push information to your destination when important events occur. They can be used to ensure that you always have the most accurate information about:
- Subscription status changes
- Disbursements to your account
- Disputes on transactions
- Sub Merchant account status changes
Notifications are delivered via HTTP POST to a destination endpoint on your server and are sent based on the triggers you choose. Each webhook contains a notification type and the full Braintree object that the notification is reporting on. This information can be used to update your system or to trigger business processes.
To configure a webhook, you'll need to:
- Create a webhook destination URL on your server
- Create a new webhook in the Control Panel by entering your webhook destination URL and selecting at least one type of notification for the webhook to fire on
- When you create the webhook, the gateway will verify the destination URL
- If the destination verification succeeds, you are ready to parse incoming webhooks
- Test and go live
In order to set up webhooks for your account, you need to enable your user's role to include webhooks permissions:
- Log into the Control Panel
- Navigate to Settings > Users and Roles > Manage Roles
- Assign webhooks permissions to the user's role
- The user should then see a Webhooks option in the Settings menu
The Webhooks page will allow you to create a destination URL to receive the webhook notifications. Adding a destination requires verification. For more details, see the Creating Webhooks section.
We will resend webhook notifications every hour for up to 24 hours until both of the following are true:
- The webhook responds within 30 seconds
- The webhook responds with a 200 response
We strive to send webhook notifications as quickly as events occur in our system. If you have a large number of subscriptions that are billed simultaneously (e.g. the first of the month), you may get a flood of notifications delivered within a short period of time.