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

1. Receive webhook requests as a POST to the /webhooks endpoint
2. Decode data field
   1. Separate the 16 byte initialization vector (iv) from the value
   2. Decrypt the value using the iv and AES encryption key
3. Handle decrypted data based on event 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. Manage secret keys with secure procedures to prevent leakage.

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 your organizationID and apiKey

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"
  }
}