Callback Settings

These settings are related to the technical integration of BitLabs.

In this article, you will learn how to properly set up your callback links. Please note that we can only give rough instructions on how to set up the callbacks on your end, as everybody has different systems for receiving and processing callbacks.

Purpose of Callbacks

When a user completes a survey or gets a screenout reward, we send a callback. This is how we tell your server that one of your users has successfully completed a survey. You can then use the information to reward your users. You can customize the callback link to include all of the parameters you need to reward your users. To achieve this, you'll need to customize your callback URL with the desired parameters.

Types of Callbacks

BitLabs will send a callback for every transaction that involves payments or rewards. Currently, BitLabs sends these callbacks types:

  • Complete: Sent on each survey complete
  • Screenout: Sent whenever a user is rewarded for disqualifying from a survey
  • Reconciliation: Sent when a survey complete callback has to be reversed.
  • Rewarded Qualification Callback: Optional: when a user has completed their first qualification, they can be rewarded. This callback is only sent when you activate it on the publisher dashboard and NOT paid for by BitLabs. However, we do recommend giving users a start bonus as it increases their likelihood of taking surveys.

All of these callbacks work the same way, and they can be distinguished with the TYPE parameter. Therefore we highly recommend adding that parameter to your callback setup.

Step by Step Guide for setting up your Callbacks

First of all, make sure you have created your app within the BitLabs dashboard. This requires a verified BitLabs Account, which you can sign up for here if you haven't already. In the top right corner, you'll see a field to configure your postback link. That may be where you found a link to this article ;). In this field, you can start out with a link to the script you need us to call when a user has completed an offer.

To understand callbacks a little bit better, take a look at this simplified callback link we have sent out, we stripped the hashing to make it more readable:

In order to achieve this callback, here's what we've set up in the BitLabs Dashboard:


Unique delivery of callbacks

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 (TxId) in every callback that you can use to deduplicate incoming callbacks. We highly recommend including this parameter in you callbacks!

Dashboard Callback Parameters

For the main callback setup, you can use our drop-down editor to configure which information you would like to receive through the callback link. You can specify a custom name for the variable on the left and map it to a value on the right.

If you are configuring custom callbacks for the reconciliations, it is really important to stick to the right format. Common mistakes are to not include [] or to forget about %%. Always use the full variable including [%%] in your callback link on our dashboard. To see if your callback is working, use the callback testing button to send a callback to a specific user with a value of your choice. We are filling out the parameters automatically. Make sure that you are using these variables in your callback, otherwise, you cannot edit them in the testing tool.

[%VAL%]FloatUser Reward in App Currency. You can configure it in the Currency Settings.
[%UID%]StringUnique User Identifier, passed by publisher.
[%REASON%]StringExplains the reason for a screenout. It can be one of the following:
NONE: The user faced a screenout during the client survey
ERROR: Something went wrong before the user joined the client survey.
QUALITY: The user faced a screenout due to quality issues
CLICK: The user faced a screenout during the qualification process
[%TX%]StringTransaction ID. Use this to prevent double booking
[%REF%]StringReference ID. If this is not empty, it contains the transaction ID of a related callback. For example: reconciliation callbacks contain the reference id of their related complete callbacks.
[%RAW%]FloatComplete payment in USD, paid to the publisher.
[%RAT%]IntegerSurvey Rating from 0 to 5
[%NET%]StringInternal Survey Source/Mediation Layer
[%LOI%]IntegerLength of the Survey in minutes.
[%DIF%]StringDifficulty ("easy", "medium" or "hard") of the survey.
[%CAT%]StringCategory of the Survey.
[%COUNTRY%]StringThe Country the User took the survey from as ISO Code. (Example: US, DE, FR)
[%DELAY%]IntegerDelay in seconds for which BitLabs withholds a callback to the publisher. In most cases this is zero.
[%FSCORE%]StringFraud level of the user for the current callback. One of: GOOD, MEDIUM, BAD
[%V2SID%]StringUnique survey id returned in /v2/client/surveys endpoint. Only available if new integration API is used.
TAG ObjectAny parameter you've attached to the opening link.
[%OFFER_ID%]IntegerID of the completed task's offer. One offer can have many tasks.
[%OFFER_NAME%]StringLocalized name of the offer. Language is equivalent to what the user saw.
It isNONE if stateful offer conversion callbacks are disabled (this is the default). If they are enabled however, it indicates the latest state of the offer conversion.
[%TASK_ID%]IntegerID of the completed task.
&hash=[Hash]StringAlways attached: Hash of the complete URI (HEX encoded SHA-1 HMAC) with the App Secret.

Additional Parameters

You can attach all the variables specified in the table on your dashboard. Sometimes you may need additional information with your callback. In this case, you can just add custom variables to the BitLabs link you are sending your users to. We will pass the same parameter back with the callback. Of course, this is optional. Let's say you want to include the fact that your users are doing surveys on an android device in your callback. Within your app, you would attach &source=android to your BitLabs link. This will automatically be added to the callback we send, like this:

Please note that we will not be interpreting your custom variables, meaning what you send in is what is sent back to you.

Reconciliation Callbacks

These callbacks notify you when there has been a reconciliation of previous transactions. This happens when researchers are not satisfied with the answers of a user, for example when a user just chose the first option for each question without any context. In this case, the transaction has to be reversed. If you are paying users with real money, we highly recommend setting up these reconciliation callbacks as they may prevent users from cashing out unrightfully.

Although it does not happen often, note that it can happen that a complete callback receives more than one following reconciliation callback. For example: a user completes a $2 survey. After that, you receive a reconciliation callback of -$2 indicating that the complete was reconciled. Sometimes, you might receive another reconciliation callback of $2 again showing that the reconciliation was send incorrectly and should be inverted again.

Note that every reconciliation callback has a unique transaction ID that is also different from the transaction ID of the complete callback. If you need the transaction ID of the complete callback instead, have a look at the [%REF%] parameter.

Stateful Offer Callbacks


Legacy Support

During our current migration phase, stateful offer callbacks are only supported for our new offers system. So as long as this "Legcay Support" box is visible, either support both stateful and non-stateful callbacks or delay implementation until we fully support it.

Stateful offer callbacks can be enabled on the dashboard. Once enabled, callbacks are sent for state changes. This is mostly identical to non-stateful callbacks, with the main difference being that the user value and all other attributes are identical for all state updates.

Example callbacks received:


The example shows two callbacks being sent, to first complete and then reconcile an offer transaction for the same user. Note that raw & tx are identical in both callbacks.

Pending Offer Callbacks

There is a third, new offer conversion state called PENDING. This means, that the user has not yet received the reward but completed the offer and should wait for the reward. After a pending state callback is received, BitLabs will follow up with either a COMPLETED or RECONCILED callback after an unspecified amount of time. You should not pay this balance to the user before receiving a COMPLETED callback!

Your next Step

Once you are done with the setup here, BitLabs will now be sending callbacks accordingly. The next step will be to receive the callbacks properly. This depends on your use case, but it is always key to validate the callbacks before crediting users. Next up, you will learn how to validate the hash included with the callback.