Referral Webhook¶
The Talkable Referral Webhook notifies your endpoint that an Advocate referral status has become “Approved” specifically for a Friend purchase or event.
“Approved” referral status signifies the following:
Neither Advocate nor Friend are blocked by email or IP
Advocate passed enabled fraud checks and is considered non-fraudulent
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
Note
“Approved” referral status does not guarantee that Advocate will receive a reward.
Things that can prevent Advocate or Friend from being rewarded:
Share wasn’t active at the moment of referral event creation
Advocate Referral Incentive rewards limit (per month or in total) has been reached
Coupon cycling has been detected (when Friend uses Advocate’s coupon in referred event)
Incentive criteria does not match
Rewards issuing is not allowed for auto-approved referrals
Important
Referral Webhook keeps retrying until it gets 2xx HTTP status in response. Only after that rewards associated with the referral can be paid.
When does Talkable call the Referral Webhook?
Talkable Referral Webhook is triggered any time an Advocate referral status has become “Approved” 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 — same as id, SEO friendly
type — either “StandaloneCampaign” or “DoubleSidedDealCampaign”
new_customer — whether the Advocate has to be a new customer to see the campaign
origin_min_age — seconds passed since the first site visit before the Advocate can see the campaign
origin_max_age — seconds passed since the first site visit during which the Advocate can see the campaign
joinable_category_names — categories of origins that trigger the campaign
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
type
“Purchase” for post-purchase placement
“AffiliateMember” for standalone, floating widget, or gleam placements
- “Event” for post-event placement (such as a signup/share page which triggers a
referral campaign)
id — unique identifier of the origin event
email — email address of the person
customer_id — unique external identifier of a customer who triggered the origin event
traffic_source — traffic source of the origin event
ip_address — IP address of the origin event
For Purchase:
order_number — unique identifier of the Purchase
subtotal — order subtotal for the Purchase
currency_iso_code — currency code of the Purchase, defaults to the Site’s currency
coupon_code — coupon codes used with the Purchase (separated by
,if multiple)order_date — date of the Purchase
For Event:
event_category — identifier of an action that trigger the Event (e.g.
app_installed)event_number — unique identifier of the Event within the associated event_category
subtotal — optional monetary attribute of the Event
currency_iso_code — currency code of the Event, defaults to the Site’s currency
coupon_code — coupon codes used with the Event (separated by
,if multiple)
advocate_rewards — array of hashes describing the rewards received by Advocate person (except for rewards paid in loyalty points), where each hash contains parameters:
id — unique reward ID
amount — amount of money to reward (null when non-monetary incentive is used)
email — email of the person that got reward
person — parameters describing the person that got reward
email — person’s email address
phone_number — person’s phone number (optional)
first_name — person’s first name (optional)
last_name — person’s last name (optional)
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_atinstead)opted_in_at — date person has subscribed (optional)
phone_opted_in_at — date person has subscribed with email (optional)
unsubscribed_at — date person has unsubscribed with phone number (optional)
custom_properties — hash of person’s custom properties (optional)
is_loyalty_member — whether the person participates in loyalty program
loyalty_member — details of the person as a loyalty program participant (optional)
referral_counts — referral counts of person as Advocate
total — created referrals count
approved — approved referrals count
pending — count of waiting for approval referrals
gender [deprecated]
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 (present if 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/share page which triggers a
referral campaign)
id — unique identifier of the origin event
email — email address of the person
customer_id — unique external identifier of a customer who triggered the origin event
traffic_source — traffic source of the origin event
ip_address — IP address of the origin event
For Purchase:
order_number — unique identifier of the Purchase
subtotal — order subtotal for the Purchase
currency_iso_code — currency code of the Purchase, defaults to the Site’s currency
coupon_code — coupon codes used with the Purchase (separated by
,if multiple)order_date — date of the Purchase
For Event:
event_category — identifier of an action that trigger the Event (e.g.
app_installed)event_number — unique identifier of the Event within the associated event_category
subtotal — optional monetary attribute of the Event
currency_iso_code — currency code of the Event, defaults to the Site’s currency
coupon_code — coupon codes used with the Event (separated by
,if multiple)
friend_rewards — array of hashes describing the rewards received by referred person (except for rewards paid in loyalty points), where each hash contains parameters:
id — unique reward ID
amount — amount of money to reward (null when non-monetary incentive is used)
email — email of the person that got reward
person — parameters describing the person that got reward
email — person’s email address
phone_number — person’s phone number (optional)
first_name — person’s first name (optional)
last_name — person’s last name (optional)
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_atinstead)opted_in_at — date person has subscribed (optional)
phone_opted_in_at — date person has subscribed with email (optional)
unsubscribed_at — date person has unsubscribed with phone number (optional)
custom_properties — hash of person’s custom properties (optional)
is_loyalty_member — whether the person participates in loyalty program
loyalty_member — details of the person as a loyalty program participant (optional)
referral_counts — referral counts of person as Advocate
total — created referrals count
approved — approved referrals count
pending — count of waiting for approval referrals
gender [deprecated]
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 (present if 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/share page which triggers a
referral campaign)
id — unique identifier of the origin event
email — email address of the person
customer_id — unique external identifier of a customer who triggered the origin event
traffic_source — traffic source of the origin event
ip_address — IP address of the origin event
For Purchase:
order_number — unique identifier of the Purchase
subtotal — order subtotal for the Purchase
currency_iso_code — currency code of the Purchase, defaults to the Site’s currency
coupon_code — coupon codes used with the Purchase (separated by
,if multiple)order_date — date of the Purchase
For Event:
event_category — identifier of an action that trigger the Event (e.g.
app_installed)event_number — unique identifier of the Event within the associated event_category
subtotal — optional monetary attribute of the Event
currency_iso_code — currency code of the Event, defaults to the Site’s currency
coupon_code — coupon codes used with the Event (separated by
,if multiple)
share — details about share:
channel — sharing channel involved in the referral
referrer — Advocate referral incentive reward details (optional, absent if reward was paid in loyalty points)
id — unique reward ID
amount — amount of money to reward (null when non-monetary incentive is used)
email — email of the person that got reward
person — parameters describing the person that got reward
email — person’s email address
phone_number — person’s phone number (optional)
first_name — person’s first name (optional)
last_name — person’s last name (optional)
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_atinstead)opted_in_at — date person has subscribed (optional)
phone_opted_in_at — date person has subscribed with email (optional)
unsubscribed_at — date person has unsubscribed with phone number (optional)
custom_properties — hash of person’s custom properties (optional)
is_loyalty_member — whether the person participates in loyalty program
loyalty_member — details of the person as a loyalty program participant (optional)
referral_counts — referral counts of person as Advocate
total — created referrals count
approved — approved referrals count
pending — count of waiting for approval referrals
gender [deprecated]
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 (present if 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/share page which triggers a
referral campaign)
id — unique identifier of the origin event
email — email address of the person
customer_id — unique external identifier of a customer who triggered the origin event
traffic_source — traffic source of the origin event
ip_address — IP address of the origin event
For Purchase:
order_number — unique identifier of the Purchase
subtotal — order subtotal for the Purchase
currency_iso_code — currency code of the Purchase, defaults to the Site’s currency
coupon_code — coupon codes used with the Purchase (separated by
,if multiple)order_date — date of the Purchase
For Event:
event_category — identifier of an action that trigger the Event (e.g.
app_installed)event_number — unique identifier of the Event within the associated event_category
subtotal — optional monetary attribute of the Event
currency_iso_code — currency code of the Event, defaults to the Site’s currency
coupon_code — coupon codes used with the Event (separated by
,if multiple)
referred — Friend referred incentive reward details (optional, absent if reward was paid in loyalty points)
id — unique reward ID
amount — amount of money to reward (null when non-monetary incentive is used)
email — email of the person that got reward
person — parameters describing the person that got reward
email — person’s email address
phone_number — person’s phone number (optional)
first_name — person’s first name (optional)
last_name — person’s last name (optional)
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_atinstead)opted_in_at — date person has subscribed (optional)
phone_opted_in_at — date person has subscribed with email (optional)
unsubscribed_at — date person has unsubscribed with phone number (optional)
custom_properties — hash of person’s custom properties (optional)
is_loyalty_member — whether the person participates in loyalty program
loyalty_member — details of the person as a loyalty program participant (optional)
referral_counts — referral counts of person as Advocate
total — created referrals count
approved — approved referrals count
pending — count of waiting for approval referrals
gender [deprecated]
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 (present if 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/share page which triggers a
referral campaign)
id — unique identifier of the origin event
email — email address of the person
customer_id — unique external identifier of a customer who triggered the origin event
traffic_source — traffic source of the origin event
ip_address — IP address of the origin event
For Purchase:
order_number — unique identifier of the Purchase
subtotal — order subtotal for the Purchase
currency_iso_code — currency code of the Purchase, defaults to the Site’s currency
coupon_code — coupon codes used with the Purchase (separated by
,if multiple)order_date — date of the Purchase
For Event:
event_category — identifier of an action that trigger the Event (e.g.
app_installed)event_number — unique identifier of the Event within the associated event_category
subtotal — optional monetary attribute of the Event
currency_iso_code — currency code of the Event, defaults to the Site’s currency
coupon_code — coupon codes used with the Event (separated by
,if multiple)
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,
"joinable_category_names": ["affiliate_member"]
},
"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",
"phone_number": "+12025551111",
"first_name": "Bob",
"last_name": "Crane",
"username": null,
"sub_choice": false,
"subscribed_at": null,
"opted_in_at": null,
"phone_opted_in_at": null,
"unsubscribed_at": null,
"referral_counts": {
"total": 0,
"approved": 0,
"pending": 0
},
"custom_properties": {
"coffee_roast": "dark"
},
"is_loyalty_member": false,
"loyalty_member": null,
"gender": null
},
"amount": "5.00",
"incentive": "rebate",
"incentive_description": "$5.00 back",
"reward_coupon_code": null,
"origin": {
"id": 159843498,
"type": "AffiliateMember",
"email": "referrer@example.com",
"customer_id": "64227025",
"ip_address": "127.0.0.1",
"traffic_source": "unknown"
}
},
"referred": {
"id": 11192772,
"email": "referred@example.com",
"person": {
"email": "referred@example.com",
"phone_number": null,
"first_name": "Alice",
"last_name": "Smith",
"username": null,
"sub_choice": true,
"subscribed_at": "2018-09-14T23:57:18.734+03:00",
"opted_in_at": "2018-09-14T23:57:18.734+03:00",
"phone_opted_in_at": "2018-09-14T23:57:18.734+03:00",
"unsubscribed_at": null,
"referral_counts": {
"total": 0,
"approved": 0,
"pending": 0
},
"custom_properties": {},
"is_loyalty_member": false,
"loyalty_member": null,
"gender": null
},
"amount": "0.00",
"incentive": "other",
"incentive_description": "First Month Free",
"reward_coupon_code": null,
"origin": {
"id": 147886587,
"type": "Purchase",
"order_number": "450901776",
"order_date": "2021-04-23T19:08:17.000-08:00",
"subtotal": 35.03,
"currency_iso_code": "USD",
"email": "referred@example.com",
"customer_id": "565659001",
"ip_address": "127.0.0.1",
"coupon_code": "WHT29123",
"traffic_source": "post-checkout"
}
},
"advocate_rewards": [
{
"id": 715729561,
"email": "referrer@example.com",
"person": {
"email": "referrer@example.com",
"phone_number": "+12025551111",
"first_name": "Bob",
"last_name": "Crane",
"username": null,
"sub_choice": false,
"subscribed_at": null,
"opted_in_at": null,
"phone_opted_in_at": null,
"unsubscribed_at": null,
"referral_counts": {
"total": 0,
"approved": 0,
"pending": 0
},
"custom_properties": {
"coffee_roast": "dark"
},
"is_loyalty_member": false,
"loyalty_member": null,
"gender": null
},
"amount": "5.00",
"incentive": "rebate",
"incentive_description": "$5.00 back",
"reward_coupon_code": null,
"origin": {
"id": 6400368,
"type": "Purchase",
"order_number": "459179054",
"order_date": "2021-04-23T19:08:17.000-08:00",
"subtotal": 11.39,
"currency_iso_code": "USD",
"email": "referrer@example.com",
"customer_id": "376990942",
"ip_address": "127.0.0.1",
"coupon_code": "WHT59688",
"traffic_source": "post-checkout"
}
}
],
"friend_rewards": [
{
"id": 11192772,
"email": "referred@example.com",
"person": {
"email": "referred@example.com",
"phone_number": null,
"first_name": "Alice",
"last_name": "Smith",
"username": null,
"sub_choice": true,
"subscribed_at": "2018-09-14T23:57:18.734+03:00",
"opted_in_at": "2018-09-14T23:57:18.734+03:00",
"phone_opted_in_at": null,
"unsubscribed_at": null,
"referral_counts": {
"total": 0,
"approved": 0,
"pending": 0
},
"custom_properties": {},
"is_loyalty_member": false,
"loyalty_member": null,
"gender": null
},
"amount": "0.00",
"incentive": "other",
"incentive_description": "First Month Free",
"reward_coupon_code": null,
"origin": {
"id": 147886587,
"type": "Purchase",
"order_number": "450901776",
"order_date": "2021-04-23T19:08:17.000-08:00",
"subtotal": 35.03,
"currency_iso_code": "USD",
"email": "referred@example.com",
"customer_id": "565659001",
"ip_address": "127.0.0.1",
"coupon_code": "WHT29123",
"traffic_source": "post-checkout"
}
}
],
"referred_origin": {
"id": 6400368,
"type": "Purchase",
"order_number": "459179054",
"order_date": "2021-04-23T19:08:17.000-08:00",
"subtotal": 11.39,
"currency_iso_code": "USD",
"email": "referred@example.com",
"customer_id": "376990942",
"ip_address": "127.0.0.1",
"coupon_code": "WHT59688",
"traffic_source": "post-checkout"
},
"share": {
"channel": "other"
}
}
cURL example
curl <url> \
-d "key=<key>" \
-d "site=<site>" \
-d "type=referral_web_hook" \
-d "extras={}" \
-d 'payload={"campaign":{"id":593427266,"type":"StandaloneCampaign","cached_slug":593427266,"tag_names":["default"],"origin_min_age":null,"origin_max_age":null,"new_customer":null,"joinable_category_names":["affiliate_member"]},"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","phone_number":"+12025551111","first_name":"Bob","last_name":"Crane","username":null,"sub_choice":false,"subscribed_at":null,"opted_in_at":null,"phone_opted_in_at":null,"unsubscribed_at":null,"referral_counts":{"total":0,"approved":0,"pending":0},"custom_properties":{"coffee_roast":"dark"},"is_loyalty_member":false,"loyalty_member":null,"gender":null},"amount":"5.00","incentive":"rebate","incentive_description":"$5.00 back","reward_coupon_code":null,"origin":{"id":159843498,"type":"AffiliateMember","email":"referrer@example.com","customer_id":"64227025","ip_address":"127.0.0.1","traffic_source":"unknown"}},"referred":{"id":11192772,"email":"referred@example.com","person":{"email":"referred@example.com","phone_number":null,"first_name":"Alice","last_name":"Smith","username":null,"sub_choice":true,"subscribed_at":"2018-09-14T23:57:18.734+03:00","opted_in_at":"2018-09-14T23:57:18.734+03:00","phone_opted_in_at":"2018-09-14T23:57:18.734+03:00","unsubscribed_at":null,"referral_counts":{"total":0,"approved":0,"pending":0},"custom_properties":{},"is_loyalty_member":false,"loyalty_member":null,"gender":null},"amount":"0.00","incentive":"other","incentive_description":"First Month Free","reward_coupon_code":null,"origin":{"id":147886587,"type":"Purchase","order_number":"450901776","order_date":"2021-04-23T19:08:17.000-08:00","subtotal":35.03,"currency_iso_code":"USD","email":"referred@example.com","customer_id":"565659001","ip_address":"127.0.0.1","coupon_code":"WHT29123","traffic_source":"post-checkout"}},"advocate_rewards":[{"id":715729561,"email":"referrer@example.com","person":{"email":"referrer@example.com","phone_number":"+12025551111","first_name":"Bob","last_name":"Crane","username":null,"sub_choice":false,"subscribed_at":null,"opted_in_at":null,"phone_opted_in_at":null,"unsubscribed_at":null,"referral_counts":{"total":0,"approved":0,"pending":0},"custom_properties":{"coffee_roast":"dark"},"is_loyalty_member":false,"loyalty_member":null,"gender":null},"amount":"5.00","incentive":"rebate","incentive_description":"$5.00 back","reward_coupon_code":null,"origin":{"id":6400368,"type":"Purchase","order_number":"459179054","order_date":"2021-04-23T19:08:17.000-08:00","subtotal":11.39,"currency_iso_code":"USD","email":"referrer@example.com","customer_id":"376990942","ip_address":"127.0.0.1","coupon_code":"WHT59688","traffic_source":"post-checkout"}}],"friend_rewards":[{"id":11192772,"email":"referred@example.com","person":{"email":"referred@example.com","phone_number":null,"first_name":"Alice","last_name":"Smith","username":null,"sub_choice":true,"subscribed_at":"2018-09-14T23:57:18.734+03:00","opted_in_at":"2018-09-14T23:57:18.734+03:00","phone_opted_in_at":null,"unsubscribed_at":null,"referral_counts":{"total":0,"approved":0,"pending":0},"custom_properties":{},"is_loyalty_member":false,"loyalty_member":null,"gender":null},"amount":"0.00","incentive":"other","incentive_description":"First Month Free","reward_coupon_code":null,"origin":{"id":147886587,"type":"Purchase","order_number":"450901776","order_date":"2021-04-23T19:08:17.000-08:00","subtotal":35.03,"currency_iso_code":"USD","email":"referred@example.com","customer_id":"565659001","ip_address":"127.0.0.1","coupon_code":"WHT29123","traffic_source":"post-checkout"}}],"referred_origin":{"id":6400368,"type":"Purchase","order_number":"459179054","order_date":"2021-04-23T19:08:17.000-08:00","subtotal":11.39,"currency_iso_code":"USD","email":"referred@example.com","customer_id":"376990942","ip_address":"127.0.0.1","coupon_code":"WHT59688","traffic_source":"post-checkout"},"share":{"channel":"other"}}'