Referral Webhook¶

The Talkable Referral Webhook notifies your endpoint that an Advocate referral status has become “Approved” or “Unblocked” specifically for a Friend purchase or event.

Use cases for the Referral Webhook include:

Providing account credit or account upgrades to an Advocate as a reward
Giving non-monetary rewards such as physical gifts to an Advocate
Sending automated ‘Thank You’ emails after a reward is given to an Advocate
Data for business intelligence or analytics systems to track when Advocates receive rewards

When does Talkable call the Referral Webhook?

Talkable Referral Webhook is triggered any time an Advocate referral status has become “Approved” or “Unblocked” specifically for a Friend purchase or event.

Note: Referral Webhook triggers only for Advocate rewards specifically from a Friend Purchase or Friend Event (such as signup event or subscription purchase event). To receive notification of both Advocate and Friend rewards use the Rewards Webhook.

Payload parameters provided for Referral 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 email address
- short_url_code – unique offer ID
- ip_address
referred_origin - subhash with referred origin made by friend that created a referral
advocate_rewards — array of hashes describing the rewards received by Advocate person, where each hash contains parameters:
- email — email of the person that got reward
- person — subhash of parameters describing the person that got reward
  - 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
- amount — amount of money to reward (null when non-monetary incentive is used)
- incentive — type of incentive reward (rebate, discount_coupon, other)
- incentive_description — verbal reward explanation
- reward_coupon_code — Coupon code received by person as a reward. Only in case when incentive equals discount_coupon.
- origin — contains data about 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
friend_rewards — array of hashes describing the rewards received by referred person, where each hash contains parameters:
- email — email of the person that got reward
- person — subhash of parameters describing the person that got reward
  - 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
- amount — amount of money to reward (null when non-monetary incentive is used)
- incentive — type of incentive reward (rebate, discount_coupon, other)
- incentive_description — verbal reward explanation
- reward_coupon_code — Coupon code received by person as a reward. Only in case when incetive equals discount_coupon.
- origin — contains a data about Purchase that issued a referral

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.

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.

Sample payload

{
  "campaign": {
    "id": 593427266,
    "type": "StandaloneCampaign",
    "cached_slug": 593427266,
    "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"
  },
  "referrer": {
    "id": 715729561,
    "email": "referrer@example.com",
    "person": {
      "email": "referrer@example.com",
      "first_name": "Bob",
      "last_name": "Crane",
      "sub_choice": false,
      "subscribed_at": null,
      "opted_in_at": null,
      "unsubscribed_at": null,
      "referral_counts": {
        "total": 0,
        "approved": 0,
        "pending": 0
      }
    },
    "amount": "5.00",
    "incentive": "rebate",
    "incentive_description": "$5.00 back",
    "origin": {
      "id": 159843498,
      "type": "AffiliateMember",
      "email": "referrer@example.com",
      "customer_id": "64227025",
      "ip_address": "127.0.0.1"
    }
  },
  "referred": {
    "id": 11192772,
    "email": "referred@example.com",
    "person": {
      "email": "referred@example.com",
      "first_name": "Alice",
      "last_name": "Smith",
      "sub_choice": true,
      "subscribed_at": "2018-09-14T23:57:18.734+03:00",
      "opted_in_at": "2018-09-14T23:57:18.734+03:00",
      "unsubscribed_at": null,
      "referral_counts": {
        "total": 0,
        "approved": 0,
        "pending": 0
      }
    },
    "amount": "0.00",
    "incentive": "other",
    "incentive_description": "First Month Free",
    "origin": {
      "id": 147886587,
      "type": "Purchase",
      "order_number": "450901776",
      "subtotal": 35.03,
      "customer_id": "565659001",
      "ip_address": "127.0.0.1",
      "coupon_code": "WHT29123"
    }
  },
  "advocate_rewards": [
    {
      "id": 715729561,
      "email": "referrer@example.com",
      "person": {
        "email": "referrer@example.com",
        "first_name": "Bob",
        "last_name": "Crane",
        "gender": null,
        "sub_choice": false,
        "subscribed_at": null,
        "opted_in_at": null,
        "unsubscribed_at": null,
        "referral_counts": {
          "total": 0,
          "approved": 0,
          "pending": 0
        }
      },
      "amount": "5.00",
      "incentive": "rebate",
      "incentive_description": "$5.00 back",
      "origin": {
        "id": 159843498,
        "type": "AffiliateMember",
        "email": "referrer@example.com",
        "customer_id": "64227025",
        "ip_address": "127.0.0.1"
      }
    }
  ],
  "friend_rewards": [
    {
      "id": 11192772,
      "email": "referred@example.com",
      "person": {
        "email": "referred@example.com",
        "first_name": "Alice",
        "last_name": "Smith",
        "sub_choice": true,
        "subscribed_at": "2018-09-14T23:57:18.734+03:00",
        "opted_in_at": "2018-09-14T23:57:18.734+03:00",
        "unsubscribed_at": null,
        "referral_counts": {
          "total": 0,
          "approved": 0,
          "pending": 0
        }
      },
      "amount": "0.00",
      "incentive": "other",
      "incentive_description": "First Month Free",
      "origin": {
        "id": 147886587,
        "type": "Purchase",
        "order_number": "450901776",
        "subtotal": 35.03,
        "customer_id": "565659001",
        "ip_address": "127.0.0.1",
        "coupon_code": "WHT29123"
      }
    }
  ],
  "referred_origin": {
    "id": 6400368,
    "type": "Purchase",
    "order_number": "459179054",
    "subtotal": 11.39,
    "customer_id": "376990942",
    "ip_address": "127.0.0.1",
    "coupon_code": "WHT59688"
  }
}

cURL example

curl --data 'key=<key>&site=<site>&type=referral_web_hook&payload={"campaign":{"id":593427266,"type":"StandaloneCampaign","cached_slug":593427266,"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"},"referrer":{"id":715729561,"email":"referrer@example.com","person":{"email":"referrer@example.com","first_name":"Bob","last_name":"Crane","sub_choice":false,"subscribed_at":null,"opted_in_at":null,"unsubscribed_at":null,"referral_counts":{"total":0,"approved":0,"pending":0}},"amount":"5.00","incentive":"rebate","incentive_description":"$5.00 back","origin":{"id":159843498,"type":"AffiliateMember","email":"referrer@example.com","customer_id":"64227025","ip_address":"127.0.0.1"}},"referred":{"id":11192772,"email":"referred@example.com","person":{"email":"referred@example.com","first_name":"Alice","last_name":"Smith","sub_choice":true,"subscribed_at":"2018-09-14T23:57:18.734+03:00","opted_in_at":"2018-09-14T23:57:18.734+03:00","unsubscribed_at":null,"referral_counts":{"total":0,"approved":0,"pending":0}},"amount":"0.00","incentive":"other","incentive_description":"First Month Free","origin":{"id":147886587,"type":"Purchase","order_number":"450901776","subtotal":35.03,"customer_id":"565659001","ip_address":"127.0.0.1","coupon_code":"WHT29123"}},"advocate_rewards":[{"id":715729561,"email":"referrer@example.com","person":{"email":"referrer@example.com","first_name":"Bob","last_name":"Crane","gender":null,"sub_choice":false,"subscribed_at":null,"opted_in_at":null,"unsubscribed_at":null,"referral_counts":{"total":0,"approved":0,"pending":0}},"amount":"5.00","incentive":"rebate","incentive_description":"$5.00 back","origin":{"id":159843498,"type":"AffiliateMember","email":"referrer@example.com","customer_id":"64227025","ip_address": "127.0.0.1"}}],"friend_rewards":[{"id":11192772,"email":"referred@example.com","person":{"email":"referred@example.com","first_name":"Alice","last_name":"Smith","sub_choice":true,"subscribed_at":"2018-09-14T23:57:18.734+03:00","opted_in_at":"2018-09-14T23:57:18.734+03:00","unsubscribed_at":null,"referral_counts":{"total":0,"approved":0,"pending":0}},"amount":"0.00","incentive":"other","incentive_description":"First Month Free","origin":{"id":147886587,"type":"Purchase","order_number":"450901776","subtotal":35.03,"customer_id":"565659001","ip_address":"127.0.0.1","coupon_code":"WHT29123"}}],"referred_origin":{"id":6400368,"type":"Purchase","order_number":"459179054","subtotal":11.39,"customer_id":"376990942","ip_address":"127.0.0.1","coupon_code":"WHT59688"}}' <url>