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

The sample payload with parameters for Referral Webhook is available here: Referral Webhook Payload.

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.