Callbacks#

Callbacks (or Postbacks) allow TapResearch to notify your web-service via pre-defined callback URLs, when users receive rewards or are able to successfully initialize the SDK (In-App only).

TapResearch supports two types of callbacks and an app may only use one type of callback:

  • In-app callbacks
  • Server-to-Server

In-App Callbacks#

In-app callbacks report each reward in a separate callback. For example, if the user completes three surveys, the SDK will fire three different callbacks with three different reward amounts. Users are notified by TapResearch of the reward they will receive when in-app callbacks are used.

In-app callbacks will be fired in the following circumstances:

  • When the user closes TapResearch
  • After a successful SDK initialization

Server-to-Server Callbacks#

Server-to-Server callbacks require each app to notify their users of any rewards received. These callbacks are fired immediately after a user has earned a reward.

Update Callback URL#

The callback URL can be updated in the "Edit App" section in the Supplier Dashboard.

Suplier Dashboard

URL validation#

A valid URL needs to be entered with no spaces or special characters.

Callback testing#

The Test Callback button will generate a test complete. The test complete will fire a callback to the specified URL. It is best to test callbacks before deploying the app in production.

note

Test callbacks have a fixed currency value but values from commercial surveys will be variable.

Sample callback request#

https://www.tapresearch.com/postback?api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=
tap_37939e4ede350f3a8d5149d2fcaa025e&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout
_amount=191&payout_currency=gold&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid
=developers%40tapresearch.com&sig=b438afd7426c743e777c387d7e2712d4

Payload#

ParameterTypeDescription
uidStringPersistent unique identifier for this user.
didStringDevice identifier -- IDFA for Apple, Google Device ID for Android (May not be present if the user opted out of ad tracking).
tidStringTransaction ID or click ID. This value will not be unique if the user completed multiple surveys in a single session. Use cpid for deduping purposes.
cpidStringUnique survey complete identifier. We recommend that you store and check against this value to ensure you reward the user only once per survey complete.
api_tokenStringThis is the unique identifier we generate when you create an app in our dashboard.
payout_amountIntegerAmount of currency earned by this user.
payout_currencyStringThe type of Currency the user earned.
revenueDecimalAmount you will be paid for this survey complete in USD.
payout_typeIntegerThe action that the user was rewarded for. 0 - Profile Complete, 3 - Survey Complete.
ip_addressStringThis is the IP address of the respondent when the transaction occurred.
sigStringThis is the URL signature, which is an HMAC-MD5 generated using the query string, minus the sig parameter. See the security section for more details.

Security#

For security purposes, every callback request will include an HMAC-MD5, which is generated using the query string. Using the example request in the callback section, here are the steps to generate the HMAC-MD5. Grab your API secret. This value is located in your main dashboard. Example: 26dcc0fc7b6208fdfeffaf19f627cb4a

  • A callback request will look similar to the example shown below: https://www.tapresearch.com/postback?api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=b438afd7426c743e777c387d7e2712d4
  • Isolate the query string, leaving out the question mark. Example: api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=b438afd7426c743e777c387d7e2712d4
  • Strip out the sig parameter, including the ampersand (&) symbol. Example: api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com
  • Decode the query string. Example: api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers@tapresearch.com
  • Run the API secret and the modified payload through your favorite HMAC-MD5 generator. Using the example values in steps 1 and 2, the resulting string will be b438afd7426c743e777c387d7e2712d4.
  • Check your generated HMAC against the sig param value. If they match, then record a complete and reward the user.
# Sample request URL
url = "https://www.tapresearch.com/postback?api_token=9b99ccc0062035544a5b6579b0cfc954&cpid=tap_37939e4ede350f3a8d5149d2fcaa025e&did=0258DE71-DFEB-4399-BF26-11C1F6E600D2&payout_amount=191&revenue=0.5&tid=777ca23551a4a9173920c22e1ed7f4f3&uid=developers%40tapresearch.com&sig=b438afd7426c743e777c387d7e2712d4"
# Isolate query string
query_string = url.gsub(/^(.*?)\?/, "")
# Strip out the sig parameter
stripped_query_string = query_string.gsub(/&sig.*/, "")
# Decode URL
decoded = URI.decode(stripped_query_string)
# Generate HMAC-MD5
api_secret = "26dcc0fc7b6208fdfeffaf19f627cb4a"
digest = OpenSSL::Digest.new("md5")
md5 = OpenSSL::HMAC.hexdigest(digest, api_secret, decoded)
puts md5 # b438afd7426c743e777c387d7e2712d4

IP Whitelist#

The callbacks will be sent from the following addresses. Any other connections should be blocked.

3.88.121.21, 3.92.129.242, 3.89.214.250, 54.92.201.189, 3.84.132.120, 34.226.244.76, 52.6.75.91, 52.206.204.41, 35.168.113.51, 34.229.18.35, 35.175.253.126, 3.80.4.1, 18.212.246.233

Retries#

If a callback fails, our system will continue retrying to send the reward for 48 hours OR until a 200 response code is returned.

Callback Visualization#

Reward Callback Visualization