Callbacks
This page explains what callbacks are and how you can set up general callbacks
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.
Updated 27 days ago