Webhooks

Webhooks are used to send events from ReferralHero to your server. You can decide which events to send to your server.

To enable webhooks:

go to your campaign dashboard > Edit Campaign > Integrations > Webhooks
Click on the + New Webhook button
In the popup, add your endpoint URL and toggle the events you want to receive
Click on Create Webhook

Events

ReferralHero sends a POST HTTP request with a JSON payload when specific events occur.

There are 6 types of events:

new_registration

Sent when a new person subscribes to your list. If you the confirmation email is disabled, the event is sent as soon as the person is subscribed to the list.

{
  response: "new_registration",
  list_uuid: "MFXXXX", //The UUID of your list
  subscriber_id: "sub_123ABC", // Subscriber's ID
  name: "John Doe", //Subscriber's name
  first_name: "John",
  last_name: "Doe",
  email: "john.doe@email.com", //Subscriber's email
  extra_field: "+1 2348891123", // Subscriber's extra field's value
  extra_field_2: "USA", // Subscriber's second extra field's value
  code: "2hg36dvs", //Subscriber's unique referral code
  source: "facebook", //Subscriber's source. If the subscriber doesn't have a source the value will be "direct_visit"
  referred: true,
  referrer: {
    subscriber_id: "sub_123CCD",
    people_referred: 2,
    referral_link: "http://mywebsite.com/LINK_PLAIN",
    points: 3,
    last_referral_at: 1702017953,
    name: "Mark Doe",
    first_name: "Mark",
    last_name: "Doe",
    email: "mark@yahoo.com"
    extra_field: "+1 2348894454",
    extra_field_2: "USA",
    option_field: "Los Angeles",
    code: "fd336dff",
    phone_number: "+1 2348894454",
    crypto_wallet_address: "0x0000000000000000000000000000000000000011"
  }, //This property can have 3 possible values: an empty string (if the subscriber has not been referred), an object containing data of the referral (if the subscriber has been referred) or "subscriber_deleted" (if the subscriber has been referred but the user has been deleted.)
  referral_link: "http://mywebsite.com/LINK_PLAIN",
  created_at: 1234567889 // Timestamp of the subscriber's sign up
}

subscriber_promoted

Sent when a subscriber is promoted.

{
  response: "subscriber_promoted",
  list_uuid: "MFXXXX",
  subscriber_id: "sub_123ABC",
  source: "facebook",
  referred: false,
  referral: {
    subscriber_id: "sub_123CCD",
    people_referred: 2,
    referral_link: "http://mywebsite.com/LINK_PLAIN",
    points: 3,
    last_referral_at: 1702017953,
    name: "Mark Doe",
    first_name: "Mark",
    last_name: "Doe",
    email: "mark@yahoo.com"
    extra_field: "+1 2348894454",
    extra_field_2: "USA",
    option_field: "Los Angeles",
    code: "fd336dff",
    phone_number: "+1 2348894454",
    crypto_wallet_address: "0x0000000000000000000000000000000000000011"
  },
  people_referred: 3, //Number of people referred
  referral_link: "http://mywebsite.com/LINK_PLAIN",
  created_at: 1234567889 // Timestamp of the subscriber's promotion
  name: "John Doe", //Subscriber's name
  first_name: "John",
  last_name: "Doe",
  email: "john.doe@email.com" //Subscriber's email
  extra_field: "+1 2348891123", // Subscriber's extra field's value
  extra_field_2: "USA", // Subscriber's second extra field's value
  option_field: "Florida", // Subscriber's option field's value
  code: "2hg36dvs",
  phone_number: "+1 2348891123",
  crypto_wallet_address: "0x0000000000000000000000000000000000000000"
}

subscriber_updated

Sent when a subscriber field is updated.

{
"response": "subscriber_fields_updated",
"list_uuid": "MF833ac6ee2d", // Unique list identifier
"subscriber_id": "sub_61ad4723e3a9", // Unique ID of the subscriber
"source": "referral", // Source of the subscriber (e.g., referral, direct_visit)
"referred": false, // Whether the subscriber was referred
"referral": null,
"referral_link": "https://campaign.referralhero.com/MF833ac6ee2d/signup?mwr=1296cda7", // Personalized referral URL
"people_referred": 0,
"created_at": 1746795375, // Timestamp of subscriber creation
"last_referral_at": null,
"name": "Jane Doe", // Full name
"first_name": "Jane", // First name
"last_name": "Doe", // Last name
"email": "jane.doe@example.com", // Email address
"extra_field": "Company ABC",
"extra_field_2": "Product Manager",
"extra_field_3": "New York",
"extra_field_4": "Referral Campaign A",
"option_field": "Option 1",
"code": "1296cda7",
"phone_number": "+1234567890", // Phone number
"crypto_wallet_address": "0xABCDEF1234567890"
}

subscriber_deleted

Sent when a subscriber is deleted.

{
  response: "subscriber_deleted",
  list_uuid: "MFXXXX",
  subscriber_id: "sub_123ABC",
  last_referral_at: 1702017953,
  name: "John Doe", //Subscriber's name
  first_name: "John",
  last_name: "Doe",
  email: "john.doe@email.com" //Subscriber's email
  extra_field: "+1 2348891123", // Subscriber's extra field's value
  extra_field_2: "USA", // Subscriber's second extra field's value
  option_field: "Florida", // Subscriber's option field's value
  code: "2hg36dvs",
  phone_number: "+1 2348891123",
  crypto_wallet_address: "0x0000000000000000000000000000000000000000"
}

reward_unlocked

Sent immediately when a subscriber qualifies for and unlocks a reward.

{
"response": "reward_unlocked",
"list_uuid": "MFABC123",
"subscriber_id": "sub_ABC123",
"bonus_id": 178, // Unique ID of the reward unlocked
"reward_name": "$100 Giftcard", // Name of reward
"reward_value": 100, // Value of the reward if set
"name": "John Smith", // Subscriber's full name
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@email.com", // Subscriber's email
"extra_field": null, // Custom field #1 (optional)
"extra_field_2": null, // Custom field #2 (optional)
"extra_field_3": null, // Custom field #3 (optional)
"extra_field_4": null, // Custom field #4 (optional)
"code": "YYY999", // Unique referral code
"people_referred": 5, // Number of successful referrals
"referral_link": "ReferralHero | Referral Program Software for B2B & B2C Brands ", // Personalized referral URL
"phone_number": "", // Subscriber's phone number
"crypto_wallet_address": "" // Wallet address if used
}

reward_sent

Sent when a reward is actually delivered to the subscriber. This happens only after conditions like 'Hold until manually reviewed' or 'Hold for X days' are fulfilled or Reward delivery set to 'Unlock and send reward immediately'.

{
"response": "reward_sent",
"list_uuid": "MFABC123",
"subscriber_id": "sub_ABC123",
"bonus_id": 178, // Unique ID of the reward sent
"reward_name": "$100 Giftcard", // Name of reward
"reward_value": 100, // Value of the reward if set
"name": "John Smith", // Subscriber's full name
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@email.com", // Subscriber's email
"extra_field": null, // Custom field #1 (optional)
"extra_field_2": null, // Custom field #2 (optional)
"extra_field_3": null, // Custom field #3 (optional)
"extra_field_4": null, // Custom field #4 (optional)
"code": "YYY999", // Unique referral code
"people_referred": 5, // Number of successful referrals
"referral_link": "https://referralhero.com/?mwr=YYY999", // Personalized referral URL
"phone_number": "", // Subscriber's phone number
"crypto_wallet_address": "" // Wallet address if used
}

Errors

Please send back a blank response with a status code of 200. All not-200 responses will be considered errors. After 10 consecutive bad responses, the webhook will be disabled.

If a webhook fails, we will try to deliver it 3 times over a period of 5 minutes.

How to test a webhook

To test a webhook just click on the Test button next to the webhook URL you want to test. We will ping your webhook URL with a JSON file containing fake data.

PreviousTypeform NextZapier

Last updated 12 days ago

Was this helpful?

{ response: "new_registration", list_uuid: "MFXXXX", //The UUID of your list subscriber_id: "sub_123ABC", // Subscriber's ID name: "John Doe", //Subscriber's name first_name: "John", last_name: "Doe", email: "john.doe@email.com", //Subscriber's email extra_field: "+1 2348891123", // Subscriber's extra field's value extra_field_2: "USA", // Subscriber's second extra field's value code: "2hg36dvs", //Subscriber's unique referral code source: "facebook", //Subscriber's source. If the subscriber doesn't have a source the value will be "direct_visit" referred: true, referrer: { subscriber_id: "sub_123CCD", people_referred: 2, referral_link: "http://mywebsite.com/LINK_PLAIN", points: 3, last_referral_at: 1702017953, name: "Mark Doe", first_name: "Mark", last_name: "Doe", email: "mark@yahoo.com" extra_field: "+1 2348894454", extra_field_2: "USA", option_field: "Los Angeles", code: "fd336dff", phone_number: "+1 2348894454", crypto_wallet_address: "0x0000000000000000000000000000000000000011" }, //This property can have 3 possible values: an empty string (if the subscriber has not been referred), an object containing data of the referral (if the subscriber has been referred) or "subscriber_deleted" (if the subscriber has been referred but the user has been deleted.) referral_link: "http://mywebsite.com/LINK_PLAIN", created_at: 1234567889 // Timestamp of the subscriber's sign up }

{ response: "subscriber_promoted", list_uuid: "MFXXXX", subscriber_id: "sub_123ABC", source: "facebook", referred: false, referral: { subscriber_id: "sub_123CCD", people_referred: 2, referral_link: "http://mywebsite.com/LINK_PLAIN", points: 3, last_referral_at: 1702017953, name: "Mark Doe", first_name: "Mark", last_name: "Doe", email: "mark@yahoo.com" extra_field: "+1 2348894454", extra_field_2: "USA", option_field: "Los Angeles", code: "fd336dff", phone_number: "+1 2348894454", crypto_wallet_address: "0x0000000000000000000000000000000000000011" }, people_referred: 3, //Number of people referred referral_link: "http://mywebsite.com/LINK_PLAIN", created_at: 1234567889 // Timestamp of the subscriber's promotion name: "John Doe", //Subscriber's name first_name: "John", last_name: "Doe", email: "john.doe@email.com" //Subscriber's email extra_field: "+1 2348891123", // Subscriber's extra field's value extra_field_2: "USA", // Subscriber's second extra field's value option_field: "Florida", // Subscriber's option field's value code: "2hg36dvs", phone_number: "+1 2348891123", crypto_wallet_address: "0x0000000000000000000000000000000000000000" }

{ "response": "subscriber_fields_updated", "list_uuid": "MF833ac6ee2d", // Unique list identifier "subscriber_id": "sub_61ad4723e3a9", // Unique ID of the subscriber "source": "referral", // Source of the subscriber (e.g., referral, direct_visit) "referred": false, // Whether the subscriber was referred "referral": null, "referral_link": "https://campaign.referralhero.com/MF833ac6ee2d/signup?mwr=1296cda7", // Personalized referral URL "people_referred": 0, "created_at": 1746795375, // Timestamp of subscriber creation "last_referral_at": null, "name": "Jane Doe", // Full name "first_name": "Jane", // First name "last_name": "Doe", // Last name "email": "jane.doe@example.com", // Email address "extra_field": "Company ABC", "extra_field_2": "Product Manager", "extra_field_3": "New York", "extra_field_4": "Referral Campaign A", "option_field": "Option 1", "code": "1296cda7", "phone_number": "+1234567890", // Phone number "crypto_wallet_address": "0xABCDEF1234567890" }

{ response: "subscriber_deleted", list_uuid: "MFXXXX", subscriber_id: "sub_123ABC", last_referral_at: 1702017953, name: "John Doe", //Subscriber's name first_name: "John", last_name: "Doe", email: "john.doe@email.com" //Subscriber's email extra_field: "+1 2348891123", // Subscriber's extra field's value extra_field_2: "USA", // Subscriber's second extra field's value option_field: "Florida", // Subscriber's option field's value code: "2hg36dvs", phone_number: "+1 2348891123", crypto_wallet_address: "0x0000000000000000000000000000000000000000" }

{ "response": "reward_unlocked", "list_uuid": "MFABC123", "subscriber_id": "sub_ABC123", "bonus_id": 178, // Unique ID of the reward unlocked "reward_name": "$100 Giftcard", // Name of reward "reward_value": 100, // Value of the reward if set "name": "John Smith", // Subscriber's full name "first_name": "John", "last_name": "Smith", "email": "john.smith@email.com", // Subscriber's email "extra_field": null, // Custom field #1 (optional) "extra_field_2": null, // Custom field #2 (optional) "extra_field_3": null, // Custom field #3 (optional) "extra_field_4": null, // Custom field #4 (optional) "code": "YYY999", // Unique referral code "people_referred": 5, // Number of successful referrals "referral_link": "ReferralHero | Referral Program Software for B2B & B2C Brands ", // Personalized referral URL "phone_number": "", // Subscriber's phone number "crypto_wallet_address": "" // Wallet address if used }

{ "response": "reward_sent", "list_uuid": "MFABC123", "subscriber_id": "sub_ABC123", "bonus_id": 178, // Unique ID of the reward sent "reward_name": "$100 Giftcard", // Name of reward "reward_value": 100, // Value of the reward if set "name": "John Smith", // Subscriber's full name "first_name": "John", "last_name": "Smith", "email": "john.smith@email.com", // Subscriber's email "extra_field": null, // Custom field #1 (optional) "extra_field_2": null, // Custom field #2 (optional) "extra_field_3": null, // Custom field #3 (optional) "extra_field_4": null, // Custom field #4 (optional) "code": "YYY999", // Unique referral code "people_referred": 5, // Number of successful referrals "referral_link": "https://referralhero.com/?mwr=YYY999", // Personalized referral URL "phone_number": "", // Subscriber's phone number "crypto_wallet_address": "" // Wallet address if used }