Callbacks

The Callback is the basis by which you can reward your users. The Callback is a GET request that is sent to your processing script upon the conclusion of a transaction.

This request contains important information about the user, what survey was taken, and how much virtual currency they should receive.


Callback Responses

Example callback URL.

sometimes referring to a php, aspx, or another script depending on your webapp configuration

example-domain.com/callback

Parameters will be appended with their corresponding variables after the processing script location as follows:

example-domain.com/callback?cmd=transactionComplete&userId=user123-9370-d163590aa9&amt=100&offerInvitationId=1234&status=C&oiHash=2ef1130cca32cd030141d8935dec0992&currencyAmt=20000&transactionId=4321&endUserId=user123&offerTitle=TestProject&useragent=Peanut+Labs+Media&profiler=&currencyName=Chachingz&offerType=survey&txnHash=66a2b2987083666c76592d505240748e&program=&transactionSource=iframe&tcode=5

Query Parameters

Parameter Description
cmd Always transactionComplete.
userId Dynata userId
amt Your revenue earned for this transaction in USD.
offerInvitationId Completed survey/offer ID
status F - user screened out of survey, the required number of responses from this demographic has already been met.
C - user successfully completed the transaction.
P - user screened out of survey, does not have the relevant attributes needed.
N - prescreener over quota, prescreener termination, user duplicate digital fingerprint, User Blacklisted
R - user failed quality score threshold
T - user failed security/fraud measures
oidHash 32 character hex string = md5(concat(offerInvitationId, applicationKey))
You should verify oidHash upon receipt of the callback by recomputing it with the callback offerInvitationId and your ApplicationKey. This will secure against users faking their own id and passing it in if by some chance they come across the script.
currencyAmt Indicates how many points the user should get in your site’s virtual currency. Negative values indicate chargebacks.
transactionId Unique ID representing a single user participating in a single survey/offer, please include if requesting support for a particular transaction.
txnHash 32 character hex string = md5(concat(transactionId, current TransactionKey))
You can find your TransactionKey under your app credentials.
sub_id Alias identifier to track traffic on campaigns, can be used for testing and segmentation purposes.
tcode Provides additional data about user sessions. You can find the complete list of tcodes here.


Setup Callback

Dynata supports secure hashing on system-to-system callbacks. Please contact a Dynata account manager to configure the Callback URL. Follow the steps below to complete your setup.

How to create a processing script

  1. Create an endpoint that can receive a GET request to its location.

  2. Reward your users for completes and screen-out rewards (if applicable).

  3. Store information in your database

  4. Respond with a 1 if callback received & processed correctly.

  5. Respond with 0 if you require us to repeat the callback.

    can be repeated 3 more times

Add the callback to your application

  1. Go to Apps section in the partner portal.

  2. Select your Application.

  3. Click on the Callback section.

  4. Click on the Setup Callback button.

  5. Enter your callback URL.

  6. Click Save Changes button.



IP Whitelist

As an additional level of security, we recommend whitelisting the Dynata IP Whitelist. It can be accessed from your Dynata account under any app’s callback section. This will allow you to filter out any unexpected traffic.



How to Test the Callback

First ensure that you have whitelisted the IPs listed in the above section.

Instructions

  1. Go to Apps section.

  2. Select your Application.

  3. Click on the Callback section.

  4. Click on the Test Callback button.

  5. Fill out the form with the parameters you want and click the invoke Test Callback button.

  6. Get your results.

Callback successful
Callback successful
Callback Failed
Callback Failed