How it works

A webhook notifies you about a change in the state of an account or an investment product. These notifications are delivered to your predefined webhook URL when these changes occur. You can choose to use these notifications to carry out additional tasks within your own application. Webhook notifications are appropriate for API requests that are not immediately fulfilled

The first step in consuming a webhook is giving us a URL to deliver events to. You can submit your webhook URL on the API Config section of your accounts page. If you don’t have one, check this for how to set up one.

Once you set a webhook URL on your dashboard, we send a test webhook event to the URL  to confirm that it is set up.  Below is what the test event looks like

{
  "event": {
    "event": "test"
  }
}

Whenever certain actions occur on your integration, we trigger webhook events which your application can listen to and then carry out the applicable steps based on the response.

For example, if you implement our webhooks, once an account is successfully created on the application, we will immediately notify your server with an account.created event.

Here is a list of events we can send to your webhook URL.

Types of events

We have curated a list of events we can send to your webhook URL below.

Receiving Events

To receive our events you have to create a POST route on your application without authentication. The event object is sent in JSON as part of the request body.

from flask import Flask, request, Response
app = Flask(__name__)
@app.route('/my/webhook/url', methods=['POST'])
def respond():
print(request.json);
# Do something with event
return Response(status=200)

app.post("/my/webhook/url", function(req, response) {
  // Retrieve the request's body
  var event = req.body;
  // Do something with event
  res.send(200);
});

Verifying Events

When a webhook subscription is created, a signature is generated and provided in the response. This signature is used to sign webhook payloads sent as part of this subscription. The signature is then delivered along with each payload under the request body

The signature is essentially an HMAC SHA256 signature of your ClientID signed using your secret key.

from flask import Flask, request, Response
import hashlib, hmac
client_secret = config("CLIENT_SECRET")
client_id = config("CLIENT_ID")
app = Flask(__name__)
@app.route('/my/webhook/url', methods=['POST'])
def respond():
  # retrieve event body
  response = request.json()
  signature = response.events.get('signature')
  # validate event
  hash = hmac.new(client_secret, client_id, hashlib.sha256).hexdigest().upper()
  if hash == signature:
  # Do something with event
  return Response(status=200)

var crypto = require('crypto');
var clientSecret = process.env.CLIENT_SECRET;
var clientId = process.env.CLIENT_ID;
app.post('/my/webhook/url', function (req, res) {
  // Retrieve the request's body
  var body = req.body;
  var signature = body.events.signature;
  //validate event
  var hash = crypto.createHmac('sha256', client_Secret).update(clientId).digest('hex').toUpperCase();
  if (hash == signature) {
  // Do something with event  
  }
  res.send(200);
});

Sample Webhook Responses