What is a callback?

A callback (or postbacks or webhooks) is a process where data from BitLabs is sent to a specified server after an event has been triggered. Examples of events could be an offer completion or a survey screen-out. Data can include user ID, user rewards, and more. A callback is always an HTTP GET request. To process the data that BitLabs sends, you have to set up an Endpoint that the callback can call.

Types of callbacks

Callbacks will be sent for different demand types like offers, surveys, and magic receipts. To process callbacks, we offer a general reward callback, but we also offer callback settings specific to the different demands, which will also include more information than the general reward callback.

General reward callback

The general reward callback will be sent for a completed offer, survey magic receipt, or a reconciled survey. Read more about it here.

Offer callback

The offer callbacks will be sent for each offer complete or, if stateful offer callbacks are enabled, for each other available offer state as well. Read more about it here.

Survey callback

The survey callbacks will be sent for each survey state. The state can be read via the type parameter. Read more about it here.

Magic Receipt callback

The magic receipt callbacks will be sent for each magic receipt complete or, if stateful magic receipt callbacks are enabled, for each other available magic receipt state as well. Read more about it here.

Callback parameters

To process the callbacks, we attach certain parameters to the URL. You can read about the more specific parameters for each demand in the respective documentation, but some of them are mandatory across all demands.

All of the listed parameters will be automatically included in all your callbacks and should be handled correctly on your end:

Parameter	Type	Description
[%UID%]	String	Unique User Identifier, passed in by publisher. Max. length is 65 characters.
[%VAL%]	Float	User Reward in App Currency. You can configure it in the Currency Settings.
[%RAW%]	Float	Complete payment in USD, paid to the publisher.
[%TX%]	String	Transaction ID. Use this to prevent double-booking.
&hash=[Hash]	String	Always attached: Hash of the complete URI (HEX encoded SHA-1 HMAC) with the App Secret. We recommend using this to verify your callbacks. Read more about it here.

Additionally to all the mandatory parameters, we do offer more parameters to receive information about each conversion. Learn more about all available callback parameters here.

Callback delivery

Due to the nature of the web, we cannot guarantee to only send a callback once to you. If something on your end fails, we will retry sending the callback. Because of this, it would be detrimental if you were to process a complete callback twice and credit the user twice the amount of money. To prevent this, we send a unique Transaction ID (TX) in every callback that you can use to deduplicate incoming callbacks.

Callback security

To make sure a callback was sent by BitLabs, we add a hash to it. Learn more about securing your callback here. Additionally, you can whitelist the following IP range for callbacks and reject endpoint calls from other IPs:

20.76.54.40/29

The IP Range includes the following IPs:

20.76.54.40
20.76.54.41
20.76.54.42
20.76.54.43
20.76.54.44
20.76.54.45
20.76.54.46
20.76.54.47

Retrying failed callbacks

Our callback system is designed to automatically retry callbacks up to 10 times until we receive a 200 status code response from your endpoint. The retry will be executed with a delay (in seconds): 1, 4, 9, 16, 25, 60, 120, 300, 300, 300. When the 10th retry was still not successful, then there is no way for us to retry again.