Reward Webhook¶

The Talkable Reward Webhook notifies your endpoint that a reward is ready to be, or has been given. A reward can be for either an Advocate or for a Friend. Talkable Reward Webhook notifications allow your application to know when to reward users by means other than the standard ‘give them a coupon code’ method.

Use cases for the Reward Webhook include:

Providing account credit or account upgrades to a user as a reward
Giving non-monetary rewards such as physical gifts
Sending automated ‘Thank You’ emails after a reward is given to a user
Any event that should trigger at the moment a user has earned a reward

When does Talkable call the Reward Webhook?

Talkable calls the Reward Webhook any time a reward is ready to be, or has been given to either an Advocate or a Friend according to the logic set-up in a Talkable referral campaign.

Possible events which will trigger the Reward Webhook are:

Advocate Signup form submitted (Reason = signup)
Advocate shares an offer with Friend(s) (Reason = shared)
Friend passes email gating form (Reason = click)

Note

If campaign is setup without email gating form, Reward Webhook with Reason = click will trigger when Friend clicks through to site.
Friend makes eligible purchase (Reason = referrer)
Friend makes eligible purchase (Reason = referred)

Note

Reason = referrer indicates a reward should be given to an Advocate. Reason = referred indicates a reward should be given to a Friend.

Set-Up

Because the Reward Webhook will trigger at various events depending on the Incentive configuration for each referral campaign, to trigger the Reward Webhook we first must ensure Incentives are correctly configured. To configure incentives:

Navigate to Campaigns then select the campaign you would like to configure incentives for
Proceed to Rules then scroll down to Incentives section where incentives for both Advocates and Friends can be set-up

Configure the incentives as desired inside the Referral Incentive Editor. To configure Incentive types other than Coupon Codes, please contact your Talkable Customer Success Manager; they will be able to set up “Rebate (store credit)” type incentives and “Non-Monetary” type incentives.

Note

If there is a delay configured into when the Advocate reward is approved then the Reward Webhook trigger when the Advocate reward is ready to be, or has been given. For example, if campaigns are set to send an Advocate their reward three days after a Friend makes an eligible purchase, then the Reward Webhook will be called three days after the Friend makes the eligible purchase. You can select these delays under Fraud Settings, which is found under Menu.

Once incentives are configured for a referral campaign, Talkable will then call the Reward Webhook any time either an Advocate or a Friend should receive a reward. Now, the Reward Webhook can be set-up. Learn more about General Webhook Set Up Steps

Payload parameters provided by Reward Webhook

campaign — subhash of parameters describing the campaign
- id — unique campaign ID
- cached_slug — unique SEO friendly ID
- type — either “StandaloneCampaign” or “DoubleSidedDealCampaign”
- tag_names — array of campaign’s tags
offer — subhash of parameters describing the offer
- email — Advocate’s (referrer) email address
- short_url_code
- ip_address
person — subhash of parameters describing the person that got reward (note: might be null)
- email — person’s email address
- first_name — person’s first name
- last_name — person’s last name
- username — person’s username (optional)
- sub_choice — subscription choice (optional, present only if the form included subscription checkbox)
- subscribed_at — date person has subscribed (deprecated; use opted_in_at instead)
- opted_in_at — date person has subscribed (optional)
- unsubscribed_at — date person has unsubscribed (optional)
- custom_properties — hash of person’s custom properties (optional)
- referral_counts - subhash of Advocate’s referral counts
  - total — created referrals count
  - approved — approved referrals count
  - pending — count of waiting for approval referrals
origin — subhash of data related to the event that issued an offer
- type
  - “Purchase” for post-purchase placement
  - “AffiliateMember” for standalone, floating widget, or gleam placements
  - “Event” for post-event placement (such as a signup page which triggers a
    referral campaign)
- id — unique identifier of the origin event
- email — email address of the Advocate person
reward — subhash of parameters describing the reward itself
- reason — reason why this reward was given
- incentive_type — type of incentive (rebate, discount_coupon, other)
- incentive_description — description of incentive (human readable, equals to non monetary description if incentive_type is other)
- amount — amount of money to reward (null when incentive_type is discount_coupon or other)
- coupon_code — coupon code received by person as a reward (null when incentive_type is rebate or other)
advocate_origin - subhash of data related to the advocate event
- type
  - “Purchase” for post-purchase campaign
  - “AffiliateMember” for standalone campaign
- id — unique identifier of the advocate’s origin event
For Affiliate Member:
- email — email address of the referrer (Advocate) person
For Purchase:
- order_number - unique identifier of advocate’s order
- subtotal - advocate’s order subtotal
- email - advocate’s email address
- customer_id - unique identifier of advocate
friend_origin - subhash of data related to the friend event
- type
  - “Purchase” for post-purchase campaign
  - “Event” for custom campaign
- id — unique identifier of the friend’s origin
- order_number - unique identifier of friend’s order
- subtotal - friend’s order subtotal
- email - friend’s email address
- customer_id - unique identifier of friend

Reasons

Reward reason can be of 5 following general types.

signup — Advocate reward for sign-up (Advocate Signup form submitted)
shared — Advocate reward for sharing an offer with Friend(s)
click — Friend reward for visiting claim page (and optionally passing gating)
referrer — Advocate reward for eligible referral purchase by Friend
referred — Friend reward for eligible referral purchase by themselves

Incentive types

Incentives can be of 3 following general types.

Rebate (rebate) — monetary reward, certain amount of money that should be paid out to a customer with a given email. The merchants’ payment system should handle the payment.
Coupon code (discount_coupon) — a discount coupon is issued to user. Talkable handles distributing this type of incentives.
Non-monetary (other) — used when a campaign has a non-monetary rebate like “Free T-shirt” or “One Month Free”. This should be handled on the merchant’s side. More information on the reward is specified in incentive_description.

Coupon codes as a reward

Important

If referral campaigns are set-up to reward either Friends or Advocates with Talkable provided coupon codes, then the Reward Webhook is called for informational purposes only. It is a notification that the reward has been provided. Note, Talkable gets these coupons either by manual upload from the Dashboard, or if configured, Talkable will call the Create Coupon Webhook to generate additional coupons automatically.

Sample payload | Reason = signup

{
  "person": null,
  "origin": {
    "id": 186742865,
    "type": "AffiliateMember",
    "email": "referrer@example.com",
    "customer_id": "910930418",
    "ip_address": "127.0.0.1"
  },
  "advocate_origin": {
    "id": 186742865,
    "type": "AffiliateMember",
    "email": "referrer@example.com",
    "customer_id": "910930418",
    "ip_address": "127.0.0.1"
  },
  "friend_origin": null,
  "campaign": {
    "id": 500548529,
    "type": "StandaloneCampaign",
    "cached_slug": 500548529,
    "tag_names": ["default"],
    "origin_min_age": null,
    "origin_max_age": null,
    "new_customer": null
  },
  "offer": {
    "email": "referrer@example.com",
    "short_url_code": "1a2PV"
  },
  "reward": {
    "id": 8261257,
    "reason": "signup",
    "incentive_type": "discount_coupon",
    "incentive_description": "signup coupon \"SAMPLE-COUPON-CODE\" for $10.00 off",
    "incentive_custom_description": null,
    "amount": "10.0",
    "coupon": {
      "code": "SAMPLE-COUPON-CODE",
      "active": true,
      "valid_until": null,
      "single_use": false,
      "used": false,
      "usages": null,
      "amount": 10.0,
      "percentage_discount": null,
      "description": "$10",
      "id": 60477154,
      "expires_at": null
    },
    "coupon_code": "SAMPLE-COUPON-CODE",
    "status": "Paid"
  }
}

cURL example | Reason = signup

curl --data 'key=<key>&site=<site>&type=reward_web_hook&payload={"person":null,"origin":{"id":186742865,"type":"AffiliateMember","email":"referrer@example.com","customer_id":"910930418","ip_address":"127.0.0.1"},"advocate_origin":{"id":186742865,"type":"AffiliateMember","email":"referrer@example.com","customer_id":"910930418","ip_address":"127.0.0.1"},"friend_origin":null,"campaign":{"id":500548529,"type":"StandaloneCampaign","cached_slug":500548529,"tag_names":["default"],"origin_min_age":null,"origin_max_age":null,"new_customer":null},"offer":{"email":"referrer@example.com","short_url_code":"1a2PV","ip_address":"127.0.0.1"},"reward":{"id":8261257,"reason":"signup","incentive_type":"discount_coupon","incentive_description":"signup coupon \"SAMPLE-COUPON-CODE\" for $10.00 off","incentive_custom_description":null,"amount":"10.0","coupon":{"code":"SAMPLE-COUPON-CODE","active":true,"valid_until":null,"single_use":false,"used":false,"usages":null,"amount":10.0,"percentage_discount":null,"description":"$10","id":60477154,"expires_at":null},"coupon_code":"SAMPLE-COUPON-CODE","status":"Paid"}}' <url>

Sample payload | Reason = shared

{
  "person": null,
  "origin": {
    "id": 186742865,
    "type": "AffiliateMember",
    "email": "referrer@example.com",
    "customer_id": "910930418",
    "ip_address": "127.0.0.1"
  },
  "advocate_origin": {
    "id": 186742865,
    "type": "AffiliateMember",
    "email": "referrer@example.com",
    "customer_id": "910930418",
    "ip_address": "127.0.0.1"
  },
  "friend_origin": null,
  "campaign": {
    "id": 500548529,
    "type": "StandaloneCampaign",
    "cached_slug": 500548529,
    "tag_names": ["default"],
    "origin_min_age": null,
    "origin_max_age": null,
    "new_customer": null
  },
  "offer": {
    "email": "referrer@example.com",
    "short_url_code": "1a2PV",
    "ip_address": "127.0.0.1"
  },
  "reward": {
    "id": 8260964,
    "reason": "shared",
    "incentive_type": "discount_coupon",
    "incentive_description": "shared coupon \"SAMPLE-COUPON-CODE\" for $10.00 off",
    "incentive_custom_description": null,
    "amount": "10.0",
    "coupon": {
      "code": "SAMPLE-COUPON-CODE",
      "active": true,
      "valid_until": null,
      "single_use": false,
      "used": false,
      "usages": null,
      "amount": 10.0,
      "percentage_discount": null,
      "description": "$10",
      "id": 60477154,
      "expires_at": null
    },
    "coupon_code": "SAMPLE-COUPON-CODE",
    "status": "Paid"
  }
}

cURL example | Reason = shared

curl --data 'key=<key>&site=<site>&type=reward_web_hook&payload={"person":null,"origin":{"id":186742865,"type":"AffiliateMember","email":"referrer@example.com","customer_id":"910930418","ip_address":"127.0.0.1"},"advocate_origin":{"id":186742865,"type":"AffiliateMember","email":"referrer@example.com","customer_id":"910930418","ip_address":"127.0.0.1"},"friend_origin":null,"campaign":{"id":500548529,"type":"StandaloneCampaign","cached_slug":500548529,"tag_names":["default"],"origin_min_age":null,"origin_max_age":null,"new_customer":null},"offer":{"email":"referrer@example.com","short_url_code":"1a2PV","ip_address":"127.0.0.1"},"reward":{"id":8260964,"reason":"shared","incentive_type":"discount_coupon","incentive_description":"shared coupon \"SAMPLE-COUPON-CODE\" for $10.00 off","incentive_custom_description":null,"amount":"10.0","coupon":{"code":"SAMPLE-COUPON-CODE","active":true,"valid_until":null,"single_use":false,"used":false,"usages":null,"amount":10.0,"percentage_discount":null,"description":"$10","id":60477154,"expires_at":null},"coupon_code":"SAMPLE-COUPON-CODE","status":"Paid"}}' <url>

Sample payload | Reason = click

{
  "person": null,
  "origin": null,
  "advocate_origin": {
    "id": 395950177,
    "type": "AffiliateMember",
    "email": "referrer@example.com",
    "customer_id": "180484020",
    "ip_address": "127.0.0.1"
  },
  "friend_origin": null,
  "campaign": {
    "id": 312538309,
    "type": "StandaloneCampaign",
    "cached_slug": 312538309,
    "tag_names": ["default"],
    "origin_min_age": null,
    "origin_max_age": null,
    "new_customer": null
  },
  "offer": {
    "email": "referrer@example.com",
    "short_url_code": "1a2PV",
    "ip_address": "127.0.0.1"
  },
  "reward": {
    "id": 8261304,
    "reason": "click",
    "incentive_type": "discount_coupon",
    "incentive_description": "shared coupon \"SAMPLE-COUPON-CODE\" for $10 off",
    "incentive_custom_description": null,
    "amount": "10.0",
    "coupon": {
      "code": "SAMPLE-COUPON-CODE",
      "active": true,
      "valid_until": null,
      "single_use": false,
      "used": false,
      "usages": null,
      "amount": 10.0,
      "percentage_discount": null,
      "description": "$10",
      "id": 60477154,
      "expires_at": null
    },
    "coupon_code": "SAMPLE-COUPON-CODE",
    "status": "Paid"
  }
}

cURL example | Reason = click

curl --data 'key=<key>&site=<site>&type=reward_web_hook&payload={"person":null,"origin":null,"advocate_origin":{"id":395950177,"type":"AffiliateMember","email":"referrer@example.com","customer_id":"180484020","ip_address":"127.0.0.1"},"friend_origin":null,"campaign":{"id":312538309,"type":"StandaloneCampaign","cached_slug":312538309,"tag_names":["default"],"origin_min_age":null,"origin_max_age":null,"new_customer":null},"offer":{"email":"referrer@example.com","short_url_code":"1a2PV","ip_address":"127.0.0.1"},"reward":{"id":8261304,"reason":"click","incentive_type":"discount_coupon","incentive_description":"shared coupon \"SAMPLE-COUPON-CODE\" for $10 off","incentive_custom_description":null,"amount":"10.0","coupon":{"code":"SAMPLE-COUPON-CODE","active":true,"valid_until":null,"single_use":false,"used":false,"usages":null,"amount":10.0,"percentage_discount":null,"description":"$10","id":60477154,"expires_at":null},"coupon_code":"SAMPLE-COUPON-CODE","status":"Paid"}}' <url>

Sample payload | Reason = referrer

{
  "person": {
    "first_name": "Bob",
    "last_name": "Smith",
    "email": "referrer@example.com",
    "username": "username",
    "unsubscribed_at": null,
    "subscribed_at": "2018-08-27T21:42:23.060+03:00",
    "opted_in_at": "2018-08-27T21:42:23.060+03:00",
    "sub_choice": true,
    "referral_counts": {
      "total": 0,
      "approved": 0,
      "pending": 0
    }
  },
  "origin": {
    "id": 280695079,
    "type": "Purchase",
    "order_number": "288015920",
    "subtotal": "6.31",
    "customer_id": "230652117",
    "ip_address": "127.0.0.1",
    "coupon_code": "WHT25279"
  },
  "advocate_origin": {
    "id": 280695079,
    "type": "Purchase",
    "order_number": "288015920",
    "subtotal": "6.31",
    "customer_id": "230652117",
    "ip_address": "127.0.0.1",
    "coupon_code": "WHT25279"
  },
  "friend_origin": {
    "id": 264084636,
    "type": "Purchase",
    "order_number": "4190583",
    "subtotal": "73.41",
    "email": "referred@example.com",
    "customer_id": "323518374",
    "ip_address": "127.0.0.1",
    "coupon_code": "WHT40052"
  },
  "campaign": {
    "id": 484002505,
    "type": "StandaloneCampaign",
    "cached_slug": 484002505,
    "tag_names": ["default"],
    "origin_min_age": null,
    "origin_max_age": null,
    "new_customer": null
  },
  "offer": {
    "email": "referrer@example.com",
    "short_url_code": "1a2PV",
    "ip_address": "127.0.0.1"
  },
  "reward": {
    "id": 8261305,
    "reason": "referrer",
    "incentive_type": "rebate",
    "incentive_description": "$10.00 back",
    "incentive_custom_description": null,
    "amount": "10.0",
    "coupon": {},
    "coupon_code": null,
    "status": "Paid"
  }
}

cURL example | Reason = referrer

curl --data 'key=<key>&site=<site>&type=reward_web_hook&payload={"person":{"first_name":"Bob","last_name":"Smith","email":"referrer@example.com","username":"username","unsubscribed_at":null,"subscribed_at":"2018-08-27T21:42:23.060+03:00","opted_in_at":"2018-08-27T21:42:23.060+03:00","sub_choice":true,"referral_counts":{"total":0,"approved":0,"pending":0}},"origin":{"id":280695079,"type":"Purchase","order_number":"288015920","subtotal":"6.31","customer_id":"230652117","ip_address":"127.0.0.1","coupon_code":"WHT25279"},"advocate_origin":{"id":280695079,"type":"Purchase","order_number":"288015920","subtotal":"6.31","customer_id":"230652117","ip_address":"127.0.0.1","coupon_code":"WHT25279"},"friend_origin":{"id":264084636,"type":"Purchase","order_number":"4190583","subtotal":"73.41","email":"referred@example.com","customer_id":"323518374","ip_address":"127.0.0.1","coupon_code":"WHT40052"},"campaign":{"id":484002505,"type":"StandaloneCampaign","cached_slug":484002505,"tag_names":["default"],"origin_min_age":null,"origin_max_age":null,"new_customer":null},"offer":{"email":"referrer@example.com","short_url_code":"1a2PV","ip_address":"127.0.0.1"},"reward":{"id":8261305,"reason":"referrer","incentive_type":"rebate","incentive_description":"$10.00 back","incentive_custom_description":null,"amount":"10.0","coupon":{},"coupon_code":null,"status":"Paid"}}' <url>

Sample payload | Reason = referred

{
  "person": {
    "first_name": "Matt",
    "last_name": "Smith",
    "email": "friend@example.com",
    "username": "username",
    "unsubscribed_at": null,
    "subscribed_at": "2018-08-27T21:45:29.519+03:00",
    "opted_in_at": "2018-08-27T21:45:29.519+03:00",
    "sub_choice": true,
    "referral_counts": {
      "total": 0,
      "approved": 0,
      "pending": 0
    }
  },
  "origin": {
    "id": 818629076,
    "type": "Purchase",
    "order_number": "416466456",
    "subtotal": "48.39",
    "email": "referred@example.com",
    "customer_id": "401088820",
    "ip_address": "127.0.0.1",
    "coupon_code": "WHT862"
  },
  "advocate_origin": {
    "id": 77856467,
    "type": "Purchase",
    "order_number": "529868349",
    "subtotal": "25.76",
    "customer_id": "937735146",
    "ip_address": "127.0.0.1",
    "coupon_code": "WHT15105"
  },
  "friend_origin": {
    "id": 818629076,
    "type": "Purchase",
    "order_number": "416466456",
    "subtotal": "48.39",
    "email": "referred@example.com",
    "customer_id": "401088820",
    "ip_address": "127.0.0.1",
    "coupon_code": "WHT862"
  },
  "campaign": {
    "id": 944706822,
    "type": "StandaloneCampaign",
    "cached_slug": 944706822,
    "tag_names": ["default"],
    "origin_min_age": null,
    "origin_max_age": null,
    "new_customer": null
  },
  "offer": {
    "email": "referrer@example.com",
    "short_url_code": "1a2PV",
    "ip_address": "127.0.0.1"
  },
  "reward": {
    "id": 8261300,
    "reason": "referred",
    "incentive_type": "rebate",
    "incentive_description": "$10.00 back",
    "incentive_custom_description": null,
    "amount": "10.0",
    "coupon": {},
    "coupon_code": null,
    "status": "Paid"
  }
}

cURL example | Reason = referred

curl --data 'key=<key>&site=<site>&type=reward_web_hook&payload={"person":{"first_name":"Matt","last_name":"Smith","email":"friend@example.com","username":"username","unsubscribed_at":null,"subscribed_at":"2018-08-27T21:45:29.519+03:00","opted_in_at":"2018-08-27T21:45:29.519+03:00","sub_choice":true,"referral_counts":{"total":0,"approved":0,"pending":0}},"origin":{"id":818629076,"type":"Purchase","order_number":"416466456","subtotal":"48.39","email":"referred@example.com","customer_id":"401088820","ip_address":"127.0.0.1","coupon_code":"WHT862"},"advocate_origin":{"id":77856467,"type":"Purchase","order_number":"529868349","subtotal":"25.76","customer_id":"937735146","ip_address":"127.0.0.1","coupon_code":"WHT15105"},"friend_origin":{"id":818629076,"type":"Purchase","order_number":"416466456","subtotal":"48.39","email":"referred@example.com","customer_id":"401088820","ip_address":"127.0.0.1","coupon_code":"WHT862"},"campaign":{"id":944706822,"type":"StandaloneCampaign","cached_slug":944706822,"tag_names":["default"],"origin_min_age":null,"origin_max_age":null,"new_customer":null},"offer":{"email":"referrer@example.com","short_url_code":"1a2PV","ip_address":"127.0.0.1"},"reward":{"id":8261300,"reason":"referred","incentive_type":"rebate","incentive_description":"$10.00 back","incentive_custom_description":null,"amount":"10.0","coupon":{},"coupon_code":null,"status":"Paid"}}' <url>