Webhooks

Overview

Branch's webhook system allows you to export install and down-funnel event data as it occurs. You can import this data into your internal systems for analysis. You simply need to specify a URL for the POST or GET requests.

If you are looking for postback integrations for ad networks, please visit our Ads documentation. For pre-configured integrations into popular analytics tools, please visit our Data Integrations documentation.

The webhook system is highly customizable. You can register to only receive notifications for specific events, as well as specific subsections of events, filtered by link data, user data or event properties.

Our webhook infrastructure supports all Branch events. The data is formatted according to standard event naming and metadata format which will get you through implementation and on to analysis in no time.

Set up a webhook

Step 1: Add webhook

In the Branch Dashboard, select Data Feeds > Webhooks.
Select Add New Webhook.

Step 2: Select event for webhook

After you select Add New Webhook, complete the the following steps:

Select the drop-down menu under Select an event.

Select an event from the list. When the selected event occurs, a webhook will fire.

Tip
Events will only appear in the Select an event dropdown if at least one of those events has been recorded in the past 30 days.

Expand to view available events

Event	Description
install	Triggered the first time a user ever launches your app on their device.
reinstall	Triggered if a user deletes and reinstalls your app on their device.
open	Triggered whenever the app is opened (and the open is neither an install or reinstall)
web session start	Triggered when the user views a webpage using the Branch Web SDK
click	Triggered whenever a Branch link is clicked on any platform
-- additional events --	A complete list of events you track through the Branch Web or App SDKs.

Select Save. The Add Webhook pop-up will open.

For an exhaustive list of events and more detailed definitions of each event, please see the Event Ontology Data Schema.

Warning
Event frequency is not yet supported. At this time webhooks can only be sent every time an event occurs.

Step 3: Configure webhook

In the Free Form Edit field, 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. See our developer documentation for details on templating your postback URL with Freemarker.
Select the Filters tab.
Under Webhook details, select the POST drop-down menu. Events can be sent either via POST or GET. POST events will be created with a default POST body. See our developer documentation for details on the POST body structure.
Select POST or GET from the drop-down menu.
Select the event drop-down menu to the right of the previous drop-down. Choose which event should cause the webhook to fire. For an exhaustive list of events and more detailed definitions of each event, please see the Event Ontology Data Schema.

Warning
Apple requires users to opt into sharing their device data through Apple's AppTrackingTransparency framework. When an install is attributed to paid ads, a 2nd install event will fire post user-opt-in.
Opt-ins will affect your final install count. Our recommendation is to use a different identifier (ex. IDFV) to de-dupe install events on your internal systems.
For additional information on changes post iOS 14.5, visit our FAQ Pages

Basic filtering

In the Filters tab of the Edit/Add Webhook pop-up you can create a filter. Only events that pass the filter criteria will be sent.

Your title goes here
While Branch preserves the original case of all captured data field values and case is retained through export, when webhook/postback filters are evaluated, case-sensitivity is removed. For example, if you created a filter on user_data.os, iOS, ios, and IOS are equivalent.

A default filter that checks to see whether the event is not triggered by a known crawler/robot. To do this, we check if the operating system (OS) does not equal "robots." With that filter applied, only events without OS equal to robots (for example, iOS and Android) will trigger a webhook.

The most popular filter options are available in a drop-down menu. This should help you get up and running quickly, while also providing an example structure for more advanced filtering if you need it. See our developer documentation for implementation details on advanced filtering.

Complete the following steps to create a filter:

Click the Add New Filter button.
Select the metadata you'd like to filter with with the Field Name drop-down menu. For example, if you only want iOS installs, select Operating System from the dropdown. You'll see the text field to the right populate with the correct key.
Select equals or does not equal from next dropdown.
Enter the value of the key that you'd like to filter in or out. For example, if you want iOS installs, you'll have set up "equals" and "iOS" in the dropdowns.

Filtering example 1

For example, let's say you're interested in receiving a webhook for every install event that is referred from a Branch link where you set the Campaign field to App Install Campaign. You would configure a filter to fire a webhook only when Campaign is equal to App Install Campaign. You would select Campaign from the drop-down, the key would be be autofilled and would equal last_attributed_touch_data.~campaign. Then, you'd set the value equal to App Install Campaign.

Filtering example 2

For example, let's say you're interested in receiving a webhook for every click event that is referred from a Branch link where you set the Channel field to AppLovin. You would configure a filter to fire a webhook only when Channel is equal to AppLovin. You would select Channel from the drop-down, the key would be be autofilled and would equal last_attributed_touch_data.~channel. Finally, you'd set the value equal to AppLovin.

Testing

To test whether your webhook is configured correctly, you can use RequestBin. RequestBin gives you a URL that accepts events for 24 hours and allows you to see exactly what Branch is sending.

Go to RequestBin and select + Create Request Bin.
Copy the Endpoint URL.
Create a new webhook and use the Endpoint URL as your webhook URL.
Whenever your webhook is triggered, you will see a full report on RequestBin:

Warning
Please archive your Requestbin webhook when you have finished testing. Requestbins only last for 24 hours and return errors once they expire.

FAQs

What is the retry logic for webhooks?

We will retry if it's a timeout which can be on our end or our partner's end.

Error codes mean it succeeded from our end and the recipient responded with an error, and we don't retry those.
Since most partners' errors are caused by misconfigured webhooks and it would create a no-value load on our system.

In addition, the 500 timeout error definition is based on our setting, not based on their system, we are waiting only 2 seconds and if they did not respond back within 2 seconds we will log 500 with the timeout error message.
It is possible that they could receive data even though there is a 500 response code with a timeout error in our postback logs. When we have a waiting time (2 seconds) less than what their server took to process the request then we could see a timeout error at our end.

Note: webhook_response_time_ms in the raw data is not the time between request and response. This returns a time from postback request creation to webhooks record logging.