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 gateway.webhookNotification.parse. 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
Node.js
Copy
Copied
app.post("/webhooks", function (req, res) {
  gateway.webhookNotification.parse(
    req.body.bt_signature,
    req.body.bt_payload,
    function (err, webhookNotification) {
      console.log("[Webhook Received " + webhookNotification.timestamp + "] | Kind: " + webhookNotification.kind);

      // Example values for webhook notification properties
      console.log(webhookNotification.kind); // "subscriptionWentPastDue"
      console.log(webhookNotification.timestamp); // Sun Jan 1 00:00:00 UTC 2012
    }
  );
  res.status(200).send();
});

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 HTTP response code (i.e. ‘2xx’) within 30 seconds.

Next Page: Testing and Go Live →

Still have questions?

If you can’t find an answer, contact our Support team