API reference for webhooks
Introduction:
Webhooks are HTTP requests used to provide push notifications to Braid customers. When building Braid integrations, you might want your applications to receive events under the following situations:
- A process that you kicked off a while ago is finally complete and we want to let you know the information you requested is now ready e.g. when you (Developer) create a customer in Braid, it takes time for the Bank to approve it. The developer needs to receive a notification when the customer is approved. Similarly, when the onboarding application is submitted, UBO will receive an email to go through KYC. each UBO will do it on their time, you need to know when a UBO completes the KYC.
- We have some new information for you and you should probably ping our server to find out more e.g. you create an ACH or Wire transaction, after that you need to know the transaction status change from initiated -> submit -> sent/cancel/return, etc.
Webhook is just an endpoint on your server for Braid to call. Braid sends webhooks to programmatically inform you about changes to Braid items or the status of asynchronous processes. A successful HTTP response code (e.g. 200 or 204) is required to acknowledge receipt of the webhook from Braid. No response body is necessary.
Configuring Webhooks:
- Tell Braid about the URL: What endpoint on your server, Braid application should talk to
- Make sure your URL is working: Make sure Braid can reach that endpoint
- Add a code to process the webhook: You’ll probably want to do something meaningful in your server code once you receive that webhook
Webhook Secret
To enable webhook events, you need to register webhook endpoints. Developers receive a secret key when registering their webhook URL and selecting events.
Payload Signing
Every webhook HTTP request will contain two headers.
- X-Braid-SecurityDigest is our calculation made using the secret key to hash a concatenation of the transmission timestamp and the body of the webhook.
- X-Braid-OriginalTransmissionTime is the original timestamp which should not change if the webhook is retransmitted. This is the epoch timestamp in milliseconds.
The developer should perform their calculation using the HMAC-SHA256 algorithm and compare their result with the value in X-Braid-SecurityDigest.
Braid sends POST payloads with raw JSON to your webhook URL from one of the following IP addresses(TBD):
Note that these IP addresses are subject to change.