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 Braintree::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
post "/webhooks" do
  webhook_notification = Braintree::WebhookNotification.parse(
  puts "[Webhook Received #{webhook_notification.timestamp}] Kind: #{webhook_notification.kind}"
  return 200
# Set bt_signature_param and bt_payload_param to the "bt_signature" and "bt_payload" POST parameters
webhook_notification = Braintree::WebhookNotification.parse(
  bt_signature_param, bt_payload_param

# => "subscription_went_past_due"

# => Sun Jan 1 00:00:00 UTC 2012


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

Next: Testing and Go Live →

Still have questions?

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