Branch’s webhook system allows you to receive install and down funnel event data from us as it occurs, for install attribution or conversion funnels in your own database. Learn how to set up, test and debug issues related to it.


How To Set Up

1. Dashboard Setup - Open the Webhooks page on the Branch dashboard and click + Add New Webhook. Be sure to enable Live mode: Branch doesn’t send webhooks in Test mode.


2. Configure webhook settings - 

a. Send a webhook to: Enter the URL where you would like the events to be sent. This URL can be written with Freemarker syntax to dynamically populate parameters and execute simple, logical expressions. Note that Branch does not support the full list of Freemarker expressions due to security restrictions. Here is a list of blocked expressions:

"<#import>", "<#visit>", "<#include>", "?eval", "<#recurse>", "<#setting>", "<#macro>", "<#function>", "<#nested>", "<#return>", "<#list>"


b. Configure event trigger using a GET/POST: Events can be sent either via POST or GET. POST events will be created with a default POST body. Sample POST body below in section 3(a).

c. Users trigger event: When the selected event occurs, a webhook will fire: install, open, click, and other custom events. For an exhaustive list of events and more detailed definitions of each event, please see the Event Ontology Data Schema.

d. For filtering options (only events that pass the filter criteria will be sent), please refer to our docs here.


3. Data formatting - Branch’s powerful People-Based Attribution ensures that your metadata is consistently located across all events by following a set of data format called Event Ontology Data Schema. This consistent schema makes it easy to replicate Branch dashboards in your internal warehouse and compare large sets of data for different events. 

a. The POST body for all webhooks follows the same structure. Here is a sample POST body: 

POST
User-agent: Branch Metrics API
Content-Type: application/json
{
    "name": "<event name e.g. open>",
    "user_data": {},
    "last_cta_view_data": {},
    "last_attributed_touch_data": {},
    "custom_data": {},
    "event_data": {},
    "content_items": {},
    "timestamp": 'example timestamp (int)'
}


See how to write POST body syntax with data for an attributed open event here.

b. Advanced filtering: section 2(d) points to the documentation where we cover what basic filters do, and how to set them. Branch supports more advanced filtering which allows customers to set filters based on almost any event metadata. Find out more here.

c. Templating your Postback URL: If you'd like to template your postback URL, you’ll likely need to create one of our templated Postback URLs alongside the aforementioned filters. These work very similarly to filters but use Freemarker syntax. Follow the instructions here.


4. Testing with Requestb.in - To test whether your webhook is configured correctly, you can use requestb.in. RequestBin gives you a URL that accepts events for 24 hours and allows you to see exactly what Branch is sending. Instruction can be found here. When you have finished testing, please archive your Requestbin webhook: Requestbins only last for 24 hours and return errors once they expire. 


Troubleshoot 

Why is my webhook not firing?

  1. Is Live Mode enabled? (we don't send webhooks in test mode. Please refer to Step 1)

  2. Is base Postback URL set (refer to Step 2(a))?

  3. Is Event trigger configured (refer to Step 2(b))?

  4. Are template postback key parameters formatted correctly? (refer to 3(c))?

  5. Are you using any blocked Free Marker Expressions? (list of blocked expressions)

  6. Did you test with RequestBin and see 200 response codes with data visible?

  7. As the last step, trigger your events and ensure they appear on Liveview. If you still experience issues, please reach out to us at integrations@branch.io with your Branch key and detailed steps to reproduce your issue.


Caveats / Tips