Webhooks

Parse

When webhooks are triggered in the gateway, a notification is sent as a POST request to the specified destination URL. The post body contains two x-www-form-urlencoded parameters:

bt_signature
bt_payload

This payload is signed to ensure that the message originated from Braintree and was not modified in transit. The message is identical to standard API responses and contains a snapshot of the related entity at the time the webhook was triggered.

These parameters should be passed to the viewModel.parse_method. The result will be a WebhookNotification object consisting of:

A timestamp (in UTC)
- Tip: Notifications may not be delivered sequentially, so be sure to look at the timestamp of the event.
A kind (directly mapped to triggers)
A standard Braintree object, depending on the type of notification (e.g. a subscription object for recurring billing webhooks)
- Tip: Save webhook data to your database for reporting purposes or use it to trigger other actions in your app

PHP

if (
    isset($_POST["bt_signature"]) &&
    isset($_POST["bt_payload"])
) {
    $webhookNotification = $gateway->webhookNotification()->parse(
        $_POST["bt_signature"], $_POST["bt_payload"]
    );

    // Example values for webhook notification properties
    $message = $webhookNotification->kind; // "subscription_went_past_due"
    $message = $webhookNotification->timestamp->format('D M j G:i:s T Y'); // "Sun Jan 1 00:00:00 UTC 2012"

    file_put_contents("/tmp/webhook.log", $message, FILE_APPEND);

    header("HTTP/1.1 200 OK");
}

Notice how we are using file_put_contents to store the result of the received Webhooks to /tmp/webhooks.log.

Exceptions

An invalid signature exception is raised if the webhook notification you attempt to parse has an invalid signature.

Retries

If a webhook takes longer than 30 seconds to respond, it is considered a timeout and will be retried. We will resend webhook notifications every hour for up to 3 hours in sandbox, or up to 24 hours in production, until the webhook responds with a successful HTTPS response code (i.e. ‘2xx’) within 30 seconds.