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, offer or magic receipt complete
  • Reconciliation: Sent when a survey, offer or magic receipt complete callback has to be reversed.
  • Screenout: Sent whenever a user is rewarded for disqualifying from a survey
  • Rewarded Qualification Callback: Optional: when a user has completed their first survey 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 starting 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. You will find more information on additional offer and magic receipt callbacks below.

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 your 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.

Mandatory and recommended parameters

We recommend that you use these Parameters in your callbacks. The mandatory ones are UID, VAL and TX. Additionally, we recommend to use the Hash Parameters to ensure that the callbacks you receive are legit.

[%UID%]StringUnique User Identifier, passed by publisher.
[%VAL%]FloatUser Reward in App Currency. You can configure it in the Currency Settings.
[%TX%]StringTransaction ID. Use this to prevent double-booking.
[%RAW%]FloatComplete payment in USD, paid to the publisher.
[%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.
&hash=[Hash]StringAlways 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.

General parameters

[%APP%]StringReturns the app id of your placement/app.
[%IP%]StringIP Address of the user
[%FSCORE%]StringFraud level of the user for the current callback. One of: GOOD, MEDIUM, BAD
TAG ObjectAny parameter you've attached to the opening link.

Survey parameters

[%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
[%RAT%]IntegerSurvey Rating from 0 to 5
[%NET%]StringInternal Survey Source/Mediation Layer
[%LOI%]IntegerLength of the Survey in minutes.
[%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.
[%V2SID%]StringUnique survey id returned in /v2/client/surveys endpoint. Only available if new integration API is used.

Offer parameters

[%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.
[%OFFER_STATE%]StringIt can only be used when using Stateful Offer Callbacks. One of: NONE, COMPLETED, PENDING, RECONCILED.
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.
[%TASK_NAME%]StringLocalized name of the task. Language is equivalent to what the user saw.
[%OFFER:VC_TITLE%]StringReturns the anchor name of an offer.

Magic Receipts parameters

[%MAGIC_RECEIPT_STATE%]StringIt can only be used when using Stateful Magic Receipts Callbacks. One of: COMPLETED, PENDING, REJECTED, REVIEWING
[%MAGIC_RECEIPT_REASON%]StringReturns the reason why a receipt got rejected or approved.
[%MAGIC_RECEIPT_REASON_ID%]IntegerReturns the id of the reason.

Additional parameters for ban callbacks

[%BAN_REASON%]StringReturns the reason for a user ban.
[%BAN_STATE%]StringReturns ACTIVE or BANNED.

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. This feature is currently only available for survey callbacks.

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.

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.