Webhooks Overview with Ruby
Webhook notifications are messages indicating that an event has occurred. They are delivered via HTTP POST to a destination endpoint of your choice and can be used to update your system or to trigger business processes.
Rather than requiring you to pull information via our API, webhooks push information to your destination when important events occur. See the triggers section for a complete list of events.
In order to set up webhooks for your account, you need to enable your user’s role and privileges to include webhooks permissions. This is done in the Manage Users and Roles page in the Control Panel under the Account menu dropdown.
Once you log into the Control Panel with the appropriate permissions, you should see a Webhooks menu under the Account menu dropdown. This page will allow you to create a destination URL to receive the webhook notifications. Adding a destination requires verification. For more details, see the destination verification section.
You can create multiple webhook destination URLs as well as which webhook notifications you would like to be delivered to each endpoint.
The webhook notification message is an XML payload. This payload is signed to ensure that the message originated from Braintree and has not been modified in transit. The message is identical to standard API responses and it contains a snapshot of the related entity at the time the webhook was triggered.
You use the client library to validate the signature and parse the contents of the webhook notification. For more details, see the parsing section.
We recommend that you look at the timestamp of the events as we do not guarantee that the webhook notifications will be delivered sequentially.
If the webhook destination responds with any HTTP status code other than 200, we will consider it a failure. We also consider the request a failure if a response is not received within 30 seconds. In either case, we will resend the webhook notification every hour for up to a day. We will stop retrying if the destination responds with an HTTP status code of 200.
We strive to send webhook notifications as quickly as events occur in our system. This means that if you have a lot of subscriptions that are all set to bill at the same time (e.g., the first of the month), you may get a lot of notifications delivered within a short amount of time.