Creating Webhooks

Webhooks are configured in the Control Panel. Be sure that your user's role has webhooks permission.

Once you've created a destination URL on your own server, you can create a webhook by going to Settings > Webhooks > Create a webhook.

Destination URL

When adding a webhook in the Control Panel, you'll need to provide and verify ownership of a destination URL. This URL will receive all webhook notifications as POST requests and must be a publicly accessible URL on your site. If your site were hosted at, your webhook destination URL should look like

You are able to create multiple webhook destination URLs in order to route certain webhook notifications to specific endpoints.

Notification types

You must choose at least one notification type in order to create a webhook. Select the one(s) you want and then click Create Webhook.

Destination verification

BT challenge

When you attempt to create a new webhook, our servers will make a GET request to the provided URL with a query param named bt_challenge. This query param should be passed to the Braintree_WebhookNotification::verify. The result of calling this method should be returned as the body of the response. Your site must parse and respond to this verification request before we will send webhooks to your destination URL.

First, add a new file called webhooks.php to handle these verification GET requests.

The bt_challenge request parameter contains the string you need to pass as an argument to Braintree_WebhookNotification::verify.

require_once "PATH_TO_BRAINTREE/lib/Braintree.php";


if(isset($_GET["bt_challenge"])) {

If your server is running and correctly responding to the verification request, you should be redirected back the general webhooks page—this time with your new webhook notification listed.

If you are having issues successfully confirming your destination URL, make sure that (1) you're only passing the value returned in the result of the Braintree_WebhookNotification::verify, (2) you don't have any additional lines or spaces after the value, and (3) the HTTP response code is 200.

Next: Parsing Notifications →