Webhook Implementation
Overview
When building integrations with Branch, you might want your applications to receive events as they occur within Branch so that your backend systems can execute actions accordingly. This is implemented by developing a server endpoint to receive, decrypt, and handle webhook events. Coordinate with your Customer Support representative to send specific events to your server's webhook handling URL, and to get keys for decrypting event data and triggering test events in the Branch sandbox.
Choose which webhook events to enable
Coordinate with your Customer Support representative to discuss which webhooks are applicable for your company's use cases and how they impact user experience. See the list of available webhook events under Webhook Reference.
Get the AES Encryption Key for decoding received event data
Coordinate with your Customer Support representative to get the AES encryption key.
Example: nZFF/qfwDZVjDFlPbxAkR6tddG6zL2ytim/46HwtIM0=
Branch uses AES
with CBC
mode and PKCS5
padding to encrypt sensitive data. All sensitive data is prepended with a random initialization vector(IV)
to avoid dictionary attacks. Branch provides the AES key in BASE64
format.
Event Data Decryption Visualization
Encrypted Webhook Event:
{
"event_id": "4ddec0de-113f-45cf-9762-32bd3aef932f",
"event": "WALLET_CREATED",
"client_type": "ORGANIZATION",
"client_id": 1,
"data": "VKGi6HiSKS7oj3HrQzhbh5wUbxzIO7wNgigBzZyylhO7RU0LJ0VbGzHY9tHjNfolFv8n+M1aJ6YThCsYf1M4NrfDU9amy7D0epAstISM/jJ1k1JdFw3xTz3QAhmLRPQ3y6Hdcfi9OAyWbBk2AwnzcIXWgWiFtYYA8dDi8Iv5ITym4DJSS2v7J5yibzeH8Wn8"
}
Decrypted Webhook Event:
{
"event_id": "4ddec0de-113f-45cf-9762-32bd3aef932f",
"event": "WALLET_CREATED",
"client_type": "ORGANIZATION",
"client_id": 1,
"data": {
"employee_id": "eid1",
"account_number": "an1",
"routing_number": "rn1",
"onboarding_link": "https://test.branchapp.com/ol1"
}
}
Develop the server endpoint to receive webhooks
Set the webhook event destination URL
Provide your Customer Support representative with the URL where your server will receive webhook events at.
Example: https://api.company.com/webhooks
Server Implementation
- Receive webhook requests as a
POST
to the/webhooks
endpoint - Decode
data
field- Separate the 16 byte initialization vector (iv) from the value
- Decrypt the value using the
iv
and AES encryption key
- Handle decrypted
data
based onevent
field
Server Example
const express = require('express');
const crypto = require('crypto');
const app = express();
// receive webhook requests as a POST at /webhooks
app.post('/webhooks', express.json({ type: 'application/json' }), async (req, res) => {
// decode data block using AES encryption key
const decryptCipher = (data, key) => {
const iv = data.slice(0, 16);
const value = data.slice(16, data.length);
const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
return decipher.update(value, undefined, "utf8") + decipher.final("utf8");
};
const decrypt = (base64EncryptedValue, base64Key) => {
const encryptedByteValue = Buffer.from(base64EncryptedValue, "base64");
const key = Buffer.from(base64Key, "base64");
return decryptCipher(encryptedByteValue, key);
};
const decryptedData = decrypt(req.body.data, `YOUR_AES_ENCRYPTION_KEY`);
// check for event type
switch(req.body.event) {
case 'WALLET_CREATED':
// handle wallet created
break;
case 'CARD_ACTIVATED':
// handle card activated
break;
default:
// do nothing, log webhook
}
});
const server = app.listen(8000, '0.0.0.0', () => {
console.log('Example app listening at http://%s:%s', server.address().address, server.address().port);
});
Use the Webhook Postman collection to trigger sandbox webhook events
Sandbox webhooks are for simulation purposes only and will not update account statuses when triggered.
Get the API Key for triggering sandbox webhook events
Coordinate with your Customer Support representative to get the API key.
Example: MvCBMAIjtKB4uUXZjMTDZFL2A16u7XWN
Set up the Postman collection
Import the Postman Collection
- Click
Download Postman Collection
- Copy the URL in the browser
- Open a Postman workspace
- Click
Import
in the top left - Paste the URL
- Right click the imported Collection and select
Edit
- Click on
Variables
in the main window - Set the
Current value
of the variables to yourorganizationID
andapiKey
Trigger an event using the Postman collection
- Select an event from the collection dropdown on the left
- Adjust values in
Body
as desired - Click
Send
button
Sandbox event generation
Only the contents of the data
block should be included in the sandbox request body. The event
, event_id
, client_type
, and client_id
fields will be generated automatically.
Additionally, if you omit fields from the data
block, default values will be supplied. For example, if employee_id
is omitted from the WALLET_CREATED
data block shown below, Branch will send a webhook with employee_id: 1
inserted.
Sandbox Request to https://sandbox.branchapp.com/v1/organizations/{{organizationID}}/webhooks/WALLET_CREATED:
{
"account_number": "1234567891234567",
"routing_number": "084106768",
"onboarding_link": "https://branchapp.com/ol1"
}
Sandbox Generated Event:
{
"event": "WALLET_CREATED",
"event_id": UUID,
"client_type": "ORGANIZATION",
"client_id": "100000",
"data": {
"employee_id": "1",
"account_number": "1234567891234567",
"routing_number": "084106768",
"onboarding_link": "https://branchapp.com/ol1"
}
}
Updated 8 days ago