Real-time callbacks

A callback (also known as a postback) is a ping made between one server and another server endpoint. Adjust uses callbacks to send advertising ID, attribution details, and even in-app data to your servers. Adjust can send callbacks for any of the following Adjust-tracked events: 

  • impressions
  • clicks
  • installs
  • sessions
  • custom in-app events
  • reattributions
  • uninstalls*
  • reinstalls*
  • reattribution reinstalls*
  • updated attributions
  • ad spend**

*Only available if you have purchased our uninstall and reinstall tracking package. Contact sales@adjust.com for more information.
**Only available on the Business Pro and above pricing plan

In Adjust, you can set callbacks on a per-event level. This allows you to isolate specific in-app events and define separate data sets for each event individually. Use our basic setup instructions to set up callbacks for a select number of Adjust-tracked events or to receive the same dataset for every Adjust-tracked event. When you're finished, move on to the advanced setup instructions to receive custom data and filter callbacks.

Before you begin

Here's what you need to know before getting started.

Requirements

  • You need the capacity to receive GET syntax requests to a valid endpoint such as a business intelligence solution or data warehouse (otherwise, we advise considering Adjust's integration with Amazon S3)
  • You must whitelist the Adjust server IPs before building your callback string to ensure that only Adjust data reaches your servers
Helpful information
  • The instructions below explain how to set up callbacks in your dashboard. For instructions on how to build a callback URL, see our callback best practices.
  • Adjust cannot forward callbacks larger than 1MB

Basic setup

Set up a single event callback

In the Adjust dashboard
  1. Navigate to your app and select your app options caret (^)
  2. Select All Settings > (DATA MANAGEMENT) Raw Data Export > Real-Time Callbacks
  3. Here, you’ll see a list of all activities tracked in Adjust. This includes all automatically tracked events and your custom in-app events.
  4. Identify the event that you want called, and select the edit (pencil) icon
  5. Insert your callback URL into the CALLBACK URL field (see callback URL templates and recommended placeholders
  6. When you are happy with your callback, select UPDATE
Once complete, Adjust will begin to ping your server endpoint with user data, in real time.

Set up a global callback

A global callback is a master callback that can be set for every Adjust-tracked event. Use of a global callback ensures that you will receive the same exact data points for every event that Adjust tracks. Global callbacks are fired in addition to any other callback that you have specified. Therefore, if you set a global callback in addition to a callback at the event level, Adjust will fire two callbacks: one that contains the data requested in the global callback and one that contains the data requested at the event level.

In the Adjust dashboard
  1. Navigate to your app and select your app options caret (^)
  2. Select All Settings > (DATA MANAGEMENT) Raw Data Export > Real-Time Callbacks
  3. Here, you’ll see a list of all activities tracked in Adjust. This includes all automatically tracked events and your custom in-app events.
  4. Select ADD GLOBAL CALLBACK
  5. Insert your callback URL into the CALLBACK URL field (see callback URL templates and recommended placeholders
  6. When you are happy with your callback, select UPDATE
If you are using global callbacks, we recommend including the following Adjust placeholders in your callback string:
  • {activity_kind} - to determine the event type: impression, click, install, rejected install (for Fraud Prevention Suite only), session, reattribution, uninstall, reinstall, reattribution reinstall, updated attribution, in-app event, or ad spend (cost_updated)
  • {event} - to identify different in-app events at the event token level
  • {event_name} - to identify different in-app events by the event name, as written in the Adjust dashboard*
*Since event names can always be modified in the Adjust dashboard, the {event_name} placeholder should only be used as a human-readable label. Conversely, event tokens are permanent, and can always be referenced in your reporting as a constant identifier.

Advanced setup

Receive custom data for installs, sessions, and reattributions

Callback parameters can be set up to send custom user information to your servers with event callbacks or with session callbacks—this includes installs and reattributions. The information you can receive through these callbacks is highly customizable. Use them to extract details specific to each in-app activity, like a username, product ID, or transaction number.

A session callback parameter is a custom data point that is specific to your individual app and sent in your callback string with every install (first session), in-app session, and reattribution. Session callback parameters can be used to extract unique user information like user ID, email address, or birthdate from your app.

All session callback parameters must be coded into the Adjust SDK (see our developer instructions).

Once the session callback parameters are integrated into the Adjust SDK, Adjust will automatically transmit session callback data in your install, session, or reattribution callback string.

Note: since all in-app events are tracked during in-app sessions, Adjust will automatically send session callback information with your in-app event callbacks, as well. If you are using the same parameter name (key name) for events and sessions, then the event value will always supersede the session value. Example below:
  • On session: foo=10
  • On event: foo=25
Event callback will contain foo=25

Receive custom data points for in-app events

Adjust can track your in-app events with our SDK or through a server-to-server (S2S) integration. Please find and follow the instructions that coordinate with your current Adjust integration.
For in-app events tracked with the Adjust SDK

If you're using the Adjust SDK to track in-app events, then all event callback parameters must be coded into the Adjust SDK (see our developer instructions). Once the event callback parameters are integrated into the Adjust SDK, our backend will automatically write these custom values onto your callback URL when the event is tracked. You do not need to include event callback parameters in your callback URL string within your Adjust dashboard.

Please note that we do not store custom event data. Therefore, without the use of a callback URL, custom data will not be saved or submitted to your servers.

For in-app events tracked server-to-server (S2S)

If you are tracking your events using a sever-to-server (S2S) integration, Adjust can still report custom data points with your in-app events.

Once Adjust receives your event information, our backend will automatically write these custom values onto your callback URL when the event is tracked. You do not need to include event callback parameters in your callback URL string within your Adjust dashboard.

Please note that we do not store custom event data. Therefore, without the use of a callback URL, custom data will not be saved or submitted to your servers.

Set up multiple callbacks for the same in-app event

You can set any number of callbacks for a single event. Simply separate each URL with a single space. Instructions are as follows:

  1. Navigate to your app and select your app options caret (^)
  2. Select All Settings > (DATA MANAGEMENT) Raw Data Export > Real-Time Callbacks
  3. Here, you’ll see a list of all activities tracked in Adjust. This includes all automatically tracked events as well as your custom in-app events.
  4. Identify the event that you want called, and select the edit (pencil) icon on the far right
  5. Insert your callback URL into the CALLBACK URL field (see callback URL templates and recommended placeholders
  6. Use the spacebar on your keyboard to create a space
  7. Insert your second callback URL into the CALLBACK URL field
  8. Repeat this process as needed
  9. When you are happy with your setup, select UPDATE

Filter your data exports using conditional callbacks

A conditional callback refers to any callback sent under specified conditions. This means that the callback will only fire when certain criteria have been met. Callbacks can be filtered based on the environment setting of the Adjust SDK, device type, and more.

Identify the prefix you will use to define your condition(s):
  • equal determines that the callback will fire only on the exact specifications you set
  • notequal determines that the callback will fire for all events, except those specified
  • contained determines that the callback will fire if one or more of the specifications is met
  • notcontained determines that the callback will fire for all values except those specified
Structure your conditions using the following format: prefix, {placeholder}*, value, callback URL

*Refer to our full list of Adjust placeholders

Notes:
  • notequal can only be used with one value. If you wish to exclude multiple values, use notcontained.
  • Values comprising multiple words must be escaped with +, so my campaign becomes my+campaign.

equal example:
​equal,{environment},sandbox,http://test.your-server.com?source={tracker_name}
This conditional callback setup will send activity tracked in the sandbox environment to a test server.

You can set any number of placeholders as conditions.

equal with stringed values example:
equal,{environment}{device_type},sandboxtablet,http://test.your-server.com?source={tracker_name}
This conditional callback setup will send activity tracked on tablets in the sandbox environment to a test server.

contained can be used to cover events related to multiple specific trackers.

contained example:
contained,{event},abc123;xyz456,http://production.your-server.com?source={tracker_name}
This conditional callback setup will send events tracked with tokens abc123 or xyz456 to a production server.

Inversely, notcontained can be used to exclude activity from multiple sources.

notcontained example:
notcontained,{network_name},Organic;Facebook+Installs,http://production.your-server.com?source={tracker_name}

This conditional callback setup will send all activities tracked that do not have the network name Facebook Installs or Organic to a production server.

Callback FAQs

What is a callback string?

A callback string is a URL that consists of your server endpoint (domain and path), any appended parameters (keys), and Adjust placeholders (values).

An Adjust placeholder is a macro that allows Adjust to dynamically supply Adjust-tracked user or engagement data within the callback string. You can use any placeholder from our complete list of available Adjust placeholders in your callback string. The parameters set within your callback string are completely customizable and will be unique to the specifications of your designated server endpoint. You can append as many key-value pairings as you need, separating each set with an ampersand (&). ​

Example: 
https://mydatawarehouse.com/adjust/info?client_name={app_name}&iOS_device={idfa}&source={network}&campaign={campaign_name}

Pro tip: Define the structure of your callback URLs within your preferred text editor and then insert the final URLs into the Adjust dashboard

You can also include custom app data in your Adjust callback by setting up callback parameters within the Adjust SDK. All callback parameters are appended automatically to your callback and do not need to be added to your dashboard callback URL. (SDK instructions for iOS and Android)​​

Adjust's conditional callbacks allow you to decide exactly when certain callbacks get fired. By using conditional prefixes in conjunction with Adjust placeholders and values, you can configure callbacks that fire only when, e.g., the device is a tablet or the activity originates from a certain tracker.

What does "real-time" mean?

Real-time means that once an event is tracked in Adjust’s system, we immediately check for any callbacks registered to said event. Once we’ve identified that a callback has been requested, we submit the data to the relevant endpoints in a matter of seconds.

What is an updated attribution or reattribution callback?

Updated attribution or updated reattribution callbacks are transmitted after an install or reattribution callback and only if a user's attribution data has changed.

Sometimes, Adjust will receive attribution information from a self-attributing network after we’ve initially determined attribution or reattribution. On these rare occasions, where the user's attribution data has changed, Adjust will update the user’s attribution information in the Adjust dashboard. When this happens, Adjust can send a callback with the updated attribution information for the updated attribution.

If you’d like to receive updated attribution information, we recommend that you include the following Adjust placeholders in your callback string:
  • {outdated_tracker}: Tracker token of the user’s initial attribution
  • {outdated_tracker_name}: Tracker name of the user’s initial attribution
  • {attribution_updated_at}: Timestamp of the revised attribution
  • {activity_kind}install_update or reattribution_update
Notes:
  • Updated attribution and reattribution information is available as of March 2017
  • Updated attribution and reattribution callbacks will only contain attribution information and Adjust placeholder data

What happens if an Adjust callback fails?

  • If your server endpoint(s) are unavailable or returning a 500 response, Adjust will retry the callback in the following cadence: 10s / 1m / 10m / 1h / 5h / 24h
  • If Adjust receives a 400 response, we do not retry the callback but will alert you immediately
To maintain data security, the Adjust callback server will record the HTTP response of your endpoint and will not follow any redirects. If your server goes down and you need historical user data, we will always do our best to recall this data retroactively.

What’s the difference between a callback and a postback?

Callback: A predefined ping made by Adjust servers to a client's server when certain events are triggered.

Postback: A predefined ping made by Adjust servers to a third-party server when certain events are triggered.

Ultimately, a callback and postback are synonymous: both are an HTTP GET sent to a specified server endpoint. However, at Adjust we use these terms to differentiate GET requests made by our clients from requests from third-parties (i.e., an ad network or analytics provider).

How can I estimate the server capacity required for storing Adjust callback data?

When evaluating how fast your servers need to be and just how much data will be transmitted, it’s always our recommendation that you work upwards from the number of users in your app. If you are solely tracking one-time events, such as registrations, then the number of callbacks will scale directly in relation to your marketing activity: one callback for each converting user. Generally, callbacks for conversion events do not highly impact server bandwidth.

What's the difference between an install callback and a rejected install callback?

An install callback is transmitted upon a user's first session. Installs are automatically tracked by the Adjust SDK.

A rejected install callback is transmitted for all installs that are filtered through the Adjust Fraud Prevention Suite. An install can be rejected for any of the following reasons: anonymous IP address, click spamming, and distribution modeling.

On this topic

On this topic