S2S Callbacks

Inbrain provides call back data upon survey completion via the Callback URLs that can be set in the Publisher Dashboard:

note

These URLs will work with both http and https.

When a Survey is Completed Successfully

Upon successful completion of a survey, the Inbrain system will issue an HTTP POST JSON request with the following data to your specified Success Callback URL.

note

The “Reward” is the reward amount in IAC (In App Currency) to be awarded to your user,according to the ratio you specify in the “app settings” under Currency Value.

Example Callback:

POST ​http://yourdomainname.com/path/to/your/successendpoint
{
    "Sig": "cd917216cb4cb02648bb96ac77760269",
    "PanelistId": "​testing@inbrain.ai​",
    "RewardType": "survey_completed",
    "RewardId": "c55b3483-5755-42f8-9bc5-5c185862e35a",
    "Reward": 72,
    "SessionId": "custom_session_value",
    "RevenueAmount": 0.35,
    "IsTest": false
}

When a Survey Is NOT Completed Successfully

When a survey is not completed (user exits survey, disqualification, quota full, etc.), the Inbrain system will issue an HTTP ​POST ​a JSON request with the following data to your specified ​Failure Callback URL.

note

The “Reward” is the reward amount in IAC (In App Currency), according to the ratio you specify in the “app settings” under Currency Value.

If disqualification rewards are configured, failure callbacks may contain a reward value greater than 0.

Example Callback:

POST ​http://yourdomainname.com/path/to/your/failureendpoint
{
    "Sig": "cd917216cb4cb02648bb96ac77760269",
    "PanelistId": "​testing@inbrain.ai​",
    "RewardType": "survey_disqualified",
    "RewardId": "c55b3483-5755-42f8-9bc5-5c185862e35a",
    "Reward": 72,
    "SessionId": "custom_session_value",
    "RevenueAmount": 0.35,
    "IsTest": false
}

Explanation of Callback Properties

Property	Type	Description	Required
Signature [deprecated]	string	This is a legacy deprecated field. Please use the ‘Sig’ property instead for signature verification	true
Sig	string	Signature that you can calculate and compare to verify the authenticity of the callback request. See more on how to verify requests using ‘Sig’ in the next section.	true
PanelistId	string	The unique user_id you provided during inbrain SDK init configuration in app. We include this so you can match the callback with a specific user_id in your system.	true
UniqueSurveyId​[deprecated]	string	This is a legacy deprecated field.	true
RewardType	string	Possible values listed below along with explanations: “profiler_completed” Initial profiler survey completed “survey_completed” Survey completed successfully “survey_disqualified” Survey terminated for quality reasons. User was not a good match. “ad_hoc” Manual survey reward from inBrain due to support ticket	true
RewardId	string	Unique Identifier for a particular reward/survey completion. You can report this value back to Inbrain for any troubleshooting needs. This can also be used to check for any duplicates in the event that your system receives duplicate callback requests.	true
Reward	decimal	The value in IAC that the user should be awarded for completing (or for disqualification of) a survey. This value is calculated based on your IAC (In App Currency) setting in the publisher dashboard.	true
SessionId	string	Value that you provide (optional) during inbrain SDK init configuration in app. This can be used to pass extra user or session data back to your server.	false
RevenueAmount	decimal	Amount in USD that you earned from the survey completion. This value is calculated based on your IAC(In App Currency) setting in the publisher dashboard. Note that this value can be zero.	true
IsTest	boolean	Indicates whether or not this callback is a test callback from a simulation survey. If true, then it is a test survey callback. When receiving callbacks, use this property to double check that live users are not seeing test surveys.	true

Signature Hash Calculation

To compute and verify the ‘Sig’ property of a callback request, combine the following callback properties along with the Callback Secret found in the ​Postback ​tab of your publisher dashboard:

[PanelistId] + [RewardId] + [CallbackSecret]

Next compute an MD5 hash of the resulting concatenated string. The result should be a hash value matching the Sig property in the callback request.