Web-hook Configuration

Campaign Rewards can be configured in the AppVirality Dashboard to be reported as server-side callbacks. This is considered to be a very secure and prominent practice.

AppVirality currently allows you to host two different Growth Hacks from the Dashboard: In-App Referral Program & Loyalty Program. Each growth hack type has a slightly varying set of webhooks. Lets explore them in detail now.

• For In App Referral Campaigns
  • Type 1: For Conversion Event
  • Type 2: For Friend Reward Event
  • Type 3: For Referrer Reward Event
• For Loyalty Campaign
  • Type 1: For Conversion Event
  • Type 2: For User Reward Event

Note

Important Note

Make the Redeem Rewards API call for the user rewards redemption, to communicate AppVirality that the user’s rewards have been redeemed, after:

• You have received the Webhook on your HTTP endpoint
• Translated the Payload/JSON data into User rewards info
• Updated the appropriate User Wallet/Account, in accordance to the above translated User Rewards

Configuring Webhooks

Reward notifications through Web hooks are user-defined HTTP post backs which are triggered on pre-defined events to receive the reward/event information.

Each web hook expects a HTTP URL to deliver payload (web hook data).

To configure the Web hook URLs navigate to:

• App Details on your AppVirality Dashboard by clicking on left menu,
• Select the desired campaign from the available list (these are the ones which are either in Drafted or Live status, implying that these are the only ones which you may have created - even if partially)
• Click on More, an array of new options shall show up
• Click on Notifications
• Switch over to the Web Hooks tab

Dashboard › App Details › Select Appropriate Campaign and Click on More on the campaign card › Click on Notifications › Switch to Web Hooks tab

Notifications Navigation

OR

Navigate to:

• ‘Reward Configuration’ from your Dashboard
• Select the appropriate Campaign from the dropdown
• Select WALLET under Configure User Rewards

Webhook Configurations from Reward Configurations panel

Secure Key – This is a key parameter that is set by you to identify AppVirality as an authorized server to call the web hook

Note

Web hook call expects HTTP 200 OK Status Code as response.

In case of any failure, the re-send call attempt is made for a maximum of 5 times

For In-App Referrals

For the In App Referral growth hack, the webhook configuration requires 3 webhook URLs, where all would exist and operate on a mutually exclusive basis, i.e. they do not have any inter dependencies when it comes to their individual operation. The 3 webhooks shall hence forth be identified as follows:

• Conversion Event URL
• Friend Reward Webhook URL
• Referrer Reward Webhook URL

On Conversion Success (Conversion Event URL)

This callback is received when a successful Conversion Event is triggered. The payload contains information regarding the rewards received by Referrer and Friend.

This webhook will get fired immediately; if the user is eligible for the reward, on receiving the conversion event.

NOTE: Conversion webhook will get fired immediately on successful conversion. Fraud check will not happen by the time this webhook get’s fired. Please use Check Reward status API before rewarding the users.

Note

Method POST
Content-Type application/json

// Referrals
{
   "securekey":"123456",
   "success":true,
   "campaignid":"283",
   "campaignname":"mom+grocery",
   "eventname":"Signup",
   "growthhack":"Word_of_Mouth",
   "extraInfo":"",
   "friend":{
      "participantid":"1415731883",
      "emailid":"sureshana463@gmail.com",
      "userkey":"7312d0eac7794939b98bb836f092313d",
      "name":"",
      "storeuserid":"",
      "rewardid":"",
      "rewarddtlid":"22250",
      "reward_type":"InstoreCredits",
      "rewarded_date":"12-Oct-2016",
      "amount":"10",
      "reward_unit":"Coins",
      "reward_description":"",
      "couponcode":"",
      "expires":"",
      "platform":"Android",
      "reachedmaxlimit":"False",
      "location":"Hyderabad, Telangana, India"
   },
   "referrer":{
      "participantid":"1415731881",
      "emailid":"sureshana462@gmail.com",
      "userkey":"a2c540b5b1d2478083fba81ee53148cc",
      "name":"",
      "storeuserid":"",
      "rewarddtlid":"22249",
      "rewarded_date":"12-Oct-2016",
      "amount":"10",
      "reward_unit":"Coins",
      "reward_type":"InstoreCredits",
      "reward_description":null,
      "reviewperiod":"0",
      "platform":"Android",
      "reachedmaxlimit":"False",
      "location":"Hyderabad, Telangana, India"
   },
   "message":null
}

Payload Parameters Explained

Parameter	Description
securekey	Secure Key which is set for the Campaign post backs, get this from Dashboard > Edit Campaign
campaignid	Unique Campaign ID
campaignname	Name of the Campaign
growthhack	Growth Hack Type
eventname	Install, Signup, Transaction & Any defined Custom Events
extraInfo	Info provided during the Conversion Event. Data will be Uri encoded.
friend	Object that consists Friend details along with his reward information obtained through Referral Program
participantid	Campaign Participant ID of Friend
emailid	Email of the Friend
userkey	Userkey of the Friend
name	Name of the Friend
storeuserid	This is the ID with which you recognize the user uniquely in your store.
rewardid	Reward ID, to Track the Reward and Distribution. Generated in case of Coupon Rewards.
rewarddtlid	Reward detail ID
reward_type	Type of Reward (Coupon, InstoreCredits, Other)
rewarded_date	Reward Initiated Date (eg: 27-Mar-2015)
amount	amount of money to reward (null when non-monetary incentive is used)
reward_unit	Currency Unit of the Reward
reward_description	Description provided for reward in case of reward type Other.
couponcode	Coupon code dispatched to Friend as a reward. Only when the Reward type is coupon.
expires	Coupon expiry date.
platform	User platform (Android, iOS, Android, Web, Unknown).
location	Friend location (City, State, Country).
referrer	Object that consists Referrer details along with his reward information obtained through Referral Program
participantid	Campaign Participant ID of Referrer
emailid	Email of the Referrer
name	Name of the Referrer
userkey	Userkey of the Referrer
storeuserid	This is the ID with which you recognize the user uniquely in your store.
rewarddtlid	Reward detail ID
rewarded_date	Reward Initiated Date (eg: 27-Mar-2015)
amount	amount of reward
reward_unit	Currency Unit of the Reward
reward_type	Type of Reward (Coupon, InstoreCredits, Other)
reward_description	Description provided for reward in case of reward type Other.
reviewperiod	No of days set as Review Period for Campaign.
platform	User platform (Android, iOS, Android, Web, Unknown)
reachedmaxlimit	Will be True, if Referrer has already obtained Maximum Reward Cap for Referral Program.
location	Referrer location (City, State, Country).
user	Object that consists User details along with his reward information obtained through Loyalty Program
userkey	Userkey of the user
emailid	Email of the user
name	Name of the user
storeuserid	This is the ID with which you recognize the user uniquely in your store.
rewarddtlid	Reward detail ID
reward_type	Type of Reward (Coupon, InstoreCredits, Other)
rewarded_date	Reward Initiated Date (eg: 27-Mar-2015)
amount	amount of reward
reward_unit	Currency Unit of the Reward
reward_description	Description provided for reward in case of reward type Other.
platform	User platform (Android, iOS, Android, Web, Unknown)
reachedmaxlimit	Will be True, if User has already obtained Maximum Reward Cap for Loyalty Program.
location	User location (City, State, Country).

On Rewarding Friend (Friend Reward WebHook URL)

Triggered when a friend is rewarded

There is a delay of 5-15 minutes, for this webhook to get fired - after the Friend Reward event is received

The web hook data includes details of friend who was rewarded along with referrer details (whom he/she is referred by). Input parameters received are same as on Conversion.

Note

Method POST
Content-Type application/json

{
 "securekey":"samplessecurekey",
 "success":true,
 "campaignid":"285",
 "campaignname":"iReff",
 "eventname":"Install",
 "extraInfo":null,
 "friend":{
    "participantid":"195644",
    "emailid":"frnd.rj990@gmail.com",
    "name":null,
    "storeuserid":null,
    "rewardid":"47",
    "rewarddtlid":"9340",
    "reward_type":"InstoreCredits",
    "rewarded_date":"27-Mar-2015",
    "amount":"20",
    "reward_unit":"Rs",
    "reward_description":null,
    "couponcode":null,
    "expires":null,
    "platform":"Android",
    "location":"Hyderabad, Telangana, India"
 },
 "referrer":{
    "participantid":"195640",
    "emailid":"ref.rj@hotmail.com",
    "name":null,
    "storeuserid":null,
    "rewarddtlid":"9339",
    "rewarded_date":"27-Mar-2015",
    "amount":"10",
    "reward_unit":"Rs",
    "reward_description":null,
    "reviewperiod":"0",
    "platform":"iOS",
    "location":"Hyderabad, Telangana, India"
 },
 "message":null
}

Payload Parameters Explained

Parameter	Description
securekey	Secure Key which is set for the Campaign post backs, get this from Dashboard > Edit Campaign
campaignid	Unique Campaign ID
campaignname	Name of the Campaign
eventname	Install, Signup, Transaction & Any defined Custom Events
extrainfo	Info provided during the Conversion Event. Data will be Uri encoded.
friend	Object that consists Friend details along with his reward information
participantid	Campaign Participant ID of Friend
emailid	Email of the Friend
name	Name of the Friend
storeuserid	This is the ID with which you recognize the user uniquely in your store.
rewardid	Reward ID, to Track the Reward and Distribution
rewarddtlid	Reward detail ID
reward_type	Type of Reward (Coupon, InstoreCredits, Other)
rewarded_date	Reward Initiated Date (eg: 27-Mar-2015)
amount	amount of money to reward (null when non-monetary incentive is used)
reward_unit	Currency Unit of the Reward
reward_description	Description provided for reward in case of reward type Other.
couponcode	Coupon code dispatched to Friend as a reward. Only when the Reward type is coupon.
expires	Coupon expiry date.
platform	User platform (Android, iOS, Android, Web, Unknown).
location	Friend location (City, State, Country).
referrer	Object that consists Referrer details along with his reward information
participantid	Campaign Participant ID of Referrer
emailid	Email of the Referrer
name	Name of the Referrer
storeuserid	This is the ID with which you recognize the user uniquely in your store.
rewarddtlid	Reward detail ID
rewarded_date	Reward Initiated Date (eg: 27-Mar-2015)
amount	amount of reward
reward_unit	Currency Unit of the Reward
reward_description	Description provided for reward in case of reward type Other.
reviewperiod	No of days set as Review Period for Campaign.
platform	User platform (Android, iOS, Android, Web, Unknown)
location	Referrer location (City, State, Country).

On Rewarding Referrer (Referrer Reward WebHook URL)

Triggers on referrer meeting the eligibility criteria for the incentives configured in the campaign, but for Coupons case it is triggered after rewarding the user. The payload contains reward details which is sent to the referrer.

There is a delay of 5-15 minutes, for this webhook to get fired - after the Referrer Reward event is received

NOTE: This webhook gets called with a delay of 5 minutes, as the background service checks the user rewards against the redemption__cap for every 5 minutes. This web-hook gets triggered only if the referrer balance is greater than(or at least equal) to redemption__cap in case of Instore Credits

Note

Method POST
Content-Type application/json

//Referrals
{
 "securekey":"samplessecurekey",
 "emailid":"ref.rj@hotmail.com",
 "name":null,
 "storeuserid":null,
 "location":"Hyderabad, Telangana, India",
 "campaignid":"285",
 "campaignname":"iReff",
 "participantid":"195640",
 "rewardid":"48",
 "reward_type":"InstoreCredits",
 "rewarded_date":"27-Mar-2015",
 "amount":"10",
 "reward_unit":"Rs",
 "reward_description":null,
 "couponcode":null,
 "expires":null,
 "platform":"iOS",
 "rewarddetails":[{
     "rewarddtlid":"9339",
     "amount":"5",
     "rewarded_date":"27-Mar-2015"},
     {
     "rewarddtlid":"9340",
     "amount":"5",
     "rewarded_date":"27-Mar-2015"}]
}

Payload Parameters Explained

Parameter	Description
securekey	Secure Key which is set for the Campaign post backs, get this from Dashboard > Edit Campaign
emailid	Email of the Referrer
name	Name of the Referrer
storeuserid	This is the ID with which you recognize the user uniquely in your store.
location	Referrer location (City, State, Country).
campaignid	Unique Campaign ID
campaignname	Name of the Campaign
participantid	Campaign Participant ID of Referrer
rewardid	Reward ID, to Track the Reward and Distribution
reward_type	Type of Reward (Coupon, InstoreCredits,Other)
rewarded_date	Reward Distributed Date (eg: 27-Mar-2015)
amount	amount of money to reward (null when non-monetary incentive is used)
reward_unit	Currency Unit of the Reward
reward_description	Description provided for reward in case of reward type Other.
couponcode	Coupon code dispatched to Friend as a reward. Only when the Reward type is coupon.
expires	Coupon expiry date.
platform	User platform (Android, iOS, Android, Web, Unknown).
rewarddetails	Rewards break down
rewarddtlid	Reward detail ID
amount	amount of reward
rewarded_date	Reward Initiated Date (eg: 27-Mar-2015)

For Loyalty Campaigns

For the Loyalty growth hack, the webhook configuration requires only 2 webhook URLs, where all would exist and operate on a mutually exclusive basis, i.e. they do not have any inter dependencies when it comes to their individual operation. These two webhooks shall hence forth be identified as follows:

• Conversion Event URL
• User Reward Webhook URL

On Conversion Success (Conversion Event URL)

This callback is received when a successful Conversion Event is triggered.

This would happen in cross-validation to the Loyalty Campaign Reward Rules you would have defined on the Dashboard for your app. The payload contains information regarding the rewards being issued to the USER.

Note

Method POST
Content-Type application/json

{
   "securekey":"123456789",
   "campaignid":"664",
   "campaignname":"suresh+loyal",
   "success":true,
   "growthhack":"Loyalty_Program",
   "eventname":"install",
   "extraInfo":"",
   "friend":null,
   "referrer":null,
   "user":{
      "participantid":null,
      "userkey":"ef356008aef8485d818c7ac4571b3ca9",
      "emailid":"demo@gmail.com",
      "name":"",
      "storeuserid":"",
      "rewardid":null,
      "rewarddtlid":"21617",
      "reward_type":"Coupon",
      "rewarded_date":"3-Aug-2016",
      "amount":"10",
      "reward_unit":"Coins",
      "reward_description":"",
      "couponcode":"",
      "expires":"",
      "platform":"Android",
      "reachedmaxlimit":"False",
      "location":"Hyderabad, Telangana, India"
   }
}

Payload Parameters Explained

Parameter	Description
securekey	Secure Key which is set for the Campaign post backs, get this from Dashboard > Edit Campaign
campaignid	Unique Campaign ID
campaignname	Name of the Campaign
growthhack	Growth Hack Type
eventname	Install, Signup, Transaction & Any defined Custom Events
extraInfo	Info provided during the Conversion Event. Data will be Uri encoded.
friend	Object that consists Friend details along with his reward information obtained through Referral Program
participantid	Campaign Participant ID of Friend
emailid	Email of the Friend
userkey	Userkey of the Friend
name	Name of the Friend
storeuserid	This is the ID with which you recognize the user uniquely in your store.
rewardid	Reward ID, to Track the Reward and Distribution
rewarddtlid	Reward detail ID
reward_type	Type of Reward (Coupon, InstoreCredits, Other)
rewarded_date	Reward Initiated Date (eg: 27-Mar-2015)
amount	amount of money to reward (null when non-monetary incentive is used)
reward_unit	Currency Unit of the Reward
reward_description	Description provided for reward in case of reward type Other.
couponcode	Coupon code dispatched to Friend as a reward. Only when the Reward type is coupon.
expires	Coupon expiry date.
platform	User platform (Android, iOS, Android, Web, Unknown).
location	Friend location (City, State, Country).
referrer	Object that consists Referrer details along with his reward information obtained through Referral Program
participantid	Campaign Participant ID of Referrer
emailid	Email of the Referrer
name	Name of the Referrer
userkey	Userkey of the Referrer
storeuserid	This is the ID with which you recognize the user uniquely in your store.
rewarddtlid	Reward detail ID
rewarded_date	Reward Initiated Date (eg: 27-Mar-2015)
amount	amount of reward
reward_unit	Currency Unit of the Reward
reward_type	Type of Reward (Coupon, InstoreCredits, Other)
reward_description	Description provided for reward in case of reward type Other.
reviewperiod	No of days set as Review Period for Campaign.
platform	User platform (Android, iOS, Android, Web, Unknown)
reachedmaxlimit	Will be True, if Referrer has already obtained Maximum Reward Cap for Referral Program.
location	Referrer location (City, State, Country).
user	Object that consists User details along with his reward information obtained through Loyalty Program
userkey	Userkey of the user
emailid	Email of the user
name	Name of the user
storeuserid	This is the ID with which you recognize the user uniquely in your store.
rewarddtlid	Reward detail ID
reward_type	Type of Reward (Coupon, InstoreCredits, Other)
rewarded_date	Reward Initiated Date (eg: 27-Mar-2015)
amount	amount of reward
reward_unit	Currency Unit of the Reward
reward_description	Description provided for reward in case of reward type Other.
platform	User platform (Android, iOS, Android, Web, Unknown)
reachedmaxlimit	Will be True, if User has already obtained Maximum Reward Cap for Loyalty Program.
location	User location (City, State, Country).

On User Reward Event (User Reward Webhook URL)

Triggers on User meeting the eligibility criteria for the incentives configured in the Loyalty campaign. The payload contains reward details which is are to be updated for the user.

Note

Method POST
Content-Type application/json

{
   "securekey":"123456789",
   "emailid":"demo@gmail.com",
   "userkey":"ef356008aef8485d818c7ac4571b3ca9",
   "name":null,
   "storeuserid":null,
   "location":"Hyderabad, Telangana, India",
   "campaignid":"664",
   "campaignname":"suresh loyal",
   "participantid":"114196",
   "rewardid":"20139",
   "reward_type":"Coupon",
   "rewarded_date":"3-Aug-2016",
   "amount":"10",
   "reward_unit":"Coins",
   "reward_description":null,
   "couponcode":"second",
   "expires":"31-Aug-2016",
   "platform":"Android",
   "rewarddetails":[
      {
         "rewarddtlid":"21616",
         "amount":"10",
         "rewarded_date":"3-Aug-2016"
      }
   ]
}

Payload Parameters Explained

Parameter	Description
securekey	Secure Key which is set for the Campaign post backs, get this from Dashboard > Edit Campaign
emailid	Email of the Referrer
name	Name of the Referrer
storeuserid	This is the ID with which you recognize the user uniquely in your store.
location	User location (City, State, Country).
campaignid	Unique Campaign ID
campaignname	Name of the Campaign
participantid	Campaign Participant ID of Referrer
rewardid	Reward ID, to Track the Reward and Distribution
reward_type	Type of Reward (Coupon, InstoreCredits,Other)
rewarded_date	Reward Distributed Date (eg: 27-Mar-2015)
amount	amount of money to reward (null when non-monetary incentive is used)
reward_unit	Currency Unit of the Reward
reward_description	Description provided for reward in case of reward type Other.
couponcode	Coupon code dispatched to Friend as a reward. Only when the Reward type is coupon.
expires	Coupon expiry date.
platform	User platform (Android, iOS, Android, Web, Unknown).
rewarddetails	Rewards break down
rewarddtlid	Reward detail ID
amount	amount of reward
rewarded_date	Reward Initiated Date (eg: 27-Mar-2015)

You may need to test/inspect/debug your webhook integration while setting up the above configurations.

Go toTesting Webhooks

Download sample project on Web-hook Implementation using RESTful WCF service with C#