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. You simply need to specify a URL for us to send all this data to.

The webhook system is very powerful and 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. You can specify to only receive an event for the first time a user completes it, or every time. You can also specify to only receive events in the case of referrals.

There are two types of events that you can listen for, and each has a different format of webhook POST. The two are:

Click webhooks: Clicks are the way users interact with your Branch links. Please note that a click does not always have to take place in a browser. For example, clicking a Universal Link will open up the app directly, and therefore no browser metadata information will be present.

Event webhooks: Events are user events that either Branch generates or you generate via a call to our event tracking API. Examples are shown on the previous page of this guide.

POSTUser-agent:BranchMetricsAPIContent-Type:application/json{event:'<event name>'event_timestamp:'<time stamp for the event>'os:'iOS'|'Android',os_version:'<the OS version>',metadata:{'< ... event metadata - specified in userCompletedAction withState >'ip:'<IP of the user>',referred:'true'|'false',// if event is install / open / web session startreinstall:'true'|'false',ifeventisinstall/open},hardware_id:'IDFA'(iOS)|'Android ID'(Android),google_advertising_id:'GAID'(Androidifpresent),// optionally included:identity:'<user ID>',// specified in setIdentity// the referrer who created the new userfirst_referring_click_timestamp:'<the first click timestamp>',first_referring_click_query:{<anyqueryparametersappenededtothelink>},first_referring_identity:'<user ID who created the referring link>'-specifiedinsetIdentityfirst_referring_hardware_id:'<hardware identifier who created the referring link'first_referring_link_data:{<linkdatadictionary-seebelow>}// the referrer who referred this sessionsession_referring_click_timestamp:'<the session click timestamp>',session_referring_click_query:{<anyqueryparametersappenededtothelink>},session_referring_identity:'<user ID who created the referring link>'session_referring_hardware_id:'<hardware identifier who created the referring link'session_referring_link_data:{<linkdatadictionary-seebelow>}}// link data dictionary example{branch_id:'unique identifier for unique link',date_ms:'link creation date with millisecond',date_sec:'link creation date with second',date:'link creation date',domain:'domain label',data:{+url:<theBranchlink>,...<otherdeeplinkdata>},campaign:'campaign label',feature:'feature label',channel:'channel label'tags:[tagsarray],stage:'stage label',}

Filters allow you to specify when a webhook gets sent to your URL based off criteria matches. You can configure your filters to use any webhook keyword value by using liquid tags following this convention: {{ param.name }}.

Wildcard Filtering

If you want to filter on just a key being present, you can put a * in the value box.

Example: Filtering installs by referring link campaign

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. The key would equal session.link_data.~campaign and the value would equal App Install Campaign.

Example: Filtering clicks by link channel

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. The key would equal click.link_data.~channel and the value would equal AppLovin.

Example: Filtering custom signup event by location

Let’s say you’re interested in receiving a webhook for every sign_up event that is triggered via the userCompletedAction method in the SDKs, but only in a specific market, like Chicago. Your event metadata will look something like the following:

If you plan on sending click or install data to a third party, you’ll likely need to create one of our templated Postback URLs along side the aforementioned filters. These work very similarly to filters and use the same liquid tags structure: {{ param.name }}. Once the webhook is eligible, the correct value will be filled in to the slot.

Example: Creating a dynamic conversion postback for an ad agency

Let’s say you have created a Branch link in the Ads tab specifically for SEM campaigns and you’re going to give the link to an advertising agency. This ad agency wants to receive install conversion events from Branch by tracking your Branch link with specific query parameters. Your Branch link might potentially look something like this: http://branch.app.link/my-sf-campaign?clickId=12345.

Now, you want to report conversions back to the agency or your backend, and you know the structure of the desired Postback URL. For example, lets say you want to send a Postback to http://myagency.com/tracking?event=install&clickId=12345&idfa=.

With that information, it’s very easy to setup the correct, dynamic Postback URL using our templates. In this case, you need 3 fields to be dynamically populated:

event name

clickId

IDFA value

Branch can easily populate those fields dynamically (and potentially add a lot more as described in the next section) using the following template keys:

{{ event.name }}

{{ session.link_click.query.clickId }}

{{ device.hardware_id }}

You can create your dynamic Postback URL by using those above tags in place of where the value should go. So, in keeping with the example, the dynamic Postback URL to give to Branch would be and should be pasted into the webhook creation URL field:

Additionally, since you don’t want to send them every install event, let’s add a filter to only send the installs that are referred by links which have a clickId in the query parameter. In this case, we use a wildcard parameter (*) for the key session.link_click.query.clickId, which tells Branch to only trigger this webhook when an install event was referred by a link with a clickId.

When a Branch link is opened, triggering a click event, you may access:

Properties of the visitor who opened the link.

Properties of the link that was opened.

Key

Description

click.query.key

Any key that was appended to the link when opened. To retrieve value1 from https://[branchsubdomain]/test?param1=value1, you would use click.query.param1

click.browser.branch_id

The Branch ID we have for a user's unique broswer

click.browser.metadata.userAgent

The user agent of the browser

click.device.hardware_id

For iOS, this is the Advertising ID. For Android, this is the Android ID

click.device.metadata.google_advertising_id

Android only. The Google Advertising ID, if known

click.device.metadata.os

The OS of the device

click.device.metadata.os_version

The OS version

click.date

Time of link click

click.device will only be available for Universal/App Links without a browser redirect. Similarly, click.browser will only be available for non-Universal/App Links. Handle this appropriately in your code.

When a user triggers an event inside your app, either one created by you or one tracked by Branch automatically (install, open, referred session, and web session start), you may access:

Properties of the event.

Identity properties of the user who triggered the event.

Session properties of the user who triggered the event.

Identity vs. Session

Identity properties are set once, the very first time Branch sees a user. Once set for each user, these are never changed. Session properties are the data of the most recent record Branch has for a user.

For an initial install event, identity and session properties will be the same. For open events, session properties will be different if the user has subsequently opened another Branch link.

Event Data

Key

Description

event.name

The name of the event (e.g., install or my_custom_event)

event.metadata.referred

Equals true if user installed app after opening a Branch link

event.metadata.ip

The IP address of the user

event.metadata.key

Data defined as key when creating a custom event

event.date

Timestamp of when the event occurred

Device Data

Device data provides access to the device snapshot. Branch collects this snapshot both when a user is in the browser (via a click on a Branch link) and then after the user opens the app.

Key

Description

device.metadata.os

The OS of the device

device.metadata.os_version

The OS version of the device

device.metadata.ip

The IP address of the device

device.metadata.model

The model of the device

Identity Data

Identity data is unique for each user Branch tracks. These values are permanently tied to that user, meaning if a link with a campaign of 'google' drives an install, then that user will have a permanent identity.link_data.~campaign value equal to 'google'.

Except for identity.id, these will not be populated if the user installed your app without opening a Branch link first.

Key

Description

identity.link_data.~id

ID of the link (0 for dynamic and 3P links)

identity.link_data.~creation_source

How the link was created, e.g. iOS SDK, API, etc.

identity.link_data.~tags

Tags of the link

identity.link_data.~campaign

Campaign of the link

identity.link_data.~channel

Channel of the link

identity.link_data.~feature

Feature of the link

identity.link_data.~stage

Stage of the link

identity.link_data.$one_time_use

Whether this was a one time use link of not

identity.link_data.$one_time_use_used

Whether this one time use link was used or not

identity.link_data.$identity_id

Branch internal identity of user who generated the link

identity.link_data.$match_duration

Length of time (in milliseconds) that a match could have occured

identity.link_data.+url

The full URL of the link, e.g. [branchsubdomain]/m/abcde12345

identity.link_data.key

Any key value you specified in the link’s data dictionary

Session Data

Session data refers to the most recent record Branch has for each user, regardless of whether it reflects an install or an open event. These will not be populated if the session was not initiated by opening a Branch link.

Key

Description

session.link_click.query.key

Any key that was appended to the link when opened. To retrieve value1 from https://[branchsubdomain]/test?param1=value1, you would use session.click.query.param1.

Check to see if you are in Test Mode with your SDK. If we are sending a fake ID to simulate installs, we will not send it inside a webhook.

What is the difference between first referring data and session referring data?¶

Because webhooks are event based, and tie back to a unique user, we send you data from the link that first drove this unique user into your app. Then, if they click another Branch link later, we also send you session referring data from this second link. For an initial install event, these should be the same. For any subsequent events, session referring data may be different.