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:

https://publisher.com/complete?user_id=8cc877ee-af19-488d-b28d-216fb866b996&user_amount=500

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.

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:

https://publisher.com/complete?uid=8cc877ee-af19-488d-b28d-216fb866b996&val=500&source=android

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.