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

Description

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

{
  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: "[e-mail]", //Subscriber's email
  extra_field: "[phone]", // 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: "[e-mail]"
    extra_field: "[phone]",
    extra_field_2: "USA",
    option_field: "Los Angeles",
    code: "fd336dff",
    phone_number: "[phone]",
    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

Description

Sent when a subscriber is promoted.

Response

{
  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: "[e-mail]"
    extra_field: "[phone]",
    extra_field_2: "USA",
    option_field: "Los Angeles",
    code: "fd336dff",
    phone_number: "[phone]",
    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: "[e-mail]" //Subscriber's email
  extra_field: "[phone]", // 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: "[phone]",
  crypto_wallet_address: "0x0000000000000000000000000000000000000000"
}

subscriber_deleted

Description

Sent when a subscriber is deleted.

Response

{
  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: "[e-mail]" //Subscriber's email
  extra_field: "[phone]", // 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: "[phone]",
  crypto_wallet_address: "0x0000000000000000000000000000000000000000"
}

bonus_unlocked

Description

Sent when a subscriber unlocks a reward.

Response

{
  response: "bonus_unlocked",
  list_uuid: "MFXXXX",
  subscriber_id: "sub_123ABC",
  bonus_id: 1323, //Bonus ID
  people_referred: 3, //Number of people referred
  referral_link: "http://mywebsite.com/LINK_PLAIN",
  name: "John Doe", //Subscriber's name
  first_name: "John",
  last_name: "Doe",
  email: "[e-mail]" //Subscriber's email
  extra_field: "[phone]", // 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: "[phone]",
  crypto_wallet_address: "0x0000000000000000000000000000000000000000"
}

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.