How to call Webhooks with your ReferralAPI Campaign

Integrate a Webhook into your ReferralAPI Campaign to receive real-time notifications whenever actions occur within the referral system. Utilize the webhook to implement custom logic based on specific actions or seamlessly integrate with external applications and services. Stay informed and take immediate action on referral events to optimize your referral program's performance and enhance user engagement.

Steps to activate

Navigate to the "Settings" tab from your desired Campaign Dashboard.
Add your Webhook URL in the "Webhook URL" section as seen below.
When an action takes place, we will send a POST request to your webhook url.

Please note that any webhook POST request will timeout if it cannot establish a connection with your server in 30 seconds, or if it does not receive a response from the server in 90 seconds.

POST/[YOUR CONFIGURED URL]

Action Event

The Webhook is triggered each time an action is tracked within your campaign. This means that every successful action, whether recorded through a script or package utilizing the createAction function or via the Create Action API call, will initiate the Webhook notification. Additionally, ReferralAPI tracks the 'VISIT' action, which is triggered whenever the ReferralAPI Script/Package is initialized in the presence of a Referral Link. The Webhook also notifies for the 'VISIT' action.

Properties

Name
event
Type
string
Description
When the action is tracked, the event will always be action.
Name
payload
Type
object
Description
Payload containing all the data related to the action that is tracked.

Payload Object

Name
campaign_id
Type
string
Description
The ID of the Campaign for which the action is tracked.
Name
referral_link_id
Type
string
Description
The ID of the Referral Link in whose presence or associtation this action is triggered.
Name
referrer_id
Type
string
Description
ID of the user to which the referral link belongs to, if any. Otherwise defaults to an empty string.
Name
referred_user_id
Type
string
Description
ID of the referred user, in case action referred_user_id is provided while creating action, otherwise defaults to an empty string.
Name
action_type
Type
string
Description
Descriptive name that is assigned to the action. The action_type for every time script/package is initialised in presence of Referral Link is "VISIT".
Name
referral_code
Type
string
Description
Unique code associated with the referral link.
Name
domain
Type
string
Description
The domain from where action is tracked (Using createAction of script/npm-package). Normally belongs to domain of the Campaign URL. In case Action is created using API, domain is empty string.
Name
ip_address
Type
string
Description
The IP address of the user that triggered the action. Defaults to Unknown if unavailable.
Name
user_agent
Type
string
Description
The user's agent string. Defaults to null.
Name
timestamp
Type
string
Description
Serialized UTC timestamp of when the action was created.
Name
browser
Type
string
Description
The user's browser that was used to create the action. Defaults to Unknown.
Name
browser_version
Type
string
Description
The version of the user's browser that was used create the action. Defaults to 0.0.0.
Name
engine
Type
string
Description
The user's agent string. Defaults to an empty string.
Name
os
Type
string
Description
The user's operating system. Defaults to Unknown.
Name
os_version
Type
string
Description
The user's operating system version. Defaults to Unknown.
Name
device
Type
string
Description
The type of device used to access the link. Defaults to Unknown.
Name
device_vendor
Type
string
Description
The brand of the user's device. Defaults to Unknown.
Name
device_model
Type
string
Description
The model of the user's device. Defaults to Unknown.
Name
bot
Type
string
Description
A boolean type-casted as string, indicating whether the user is a bot.
Name
referer
Type
string
Description
The referring website's netloc. Default value is Direct.
Name
referer_url
Type
string
Description
The full URL of the referring website. Default value is Direct.
Name
continent_name
Type
string
Description
The name of the continent of the user. Defaults to Unknown.
Name
country_code
Type
string
Description
The code representing the country of the user. Defaults to Unknown.
Name
country_name
Type
string
Description
The name of the country. Defaults to Unknown.
Name
state_prov
Type
string
Description
The state or province name. Defaults to Unknown.
Name
state_prov_code
Type
string
Description
The code representing the state or province. Defaults to Unknown.
Name
city
Type
string
Description
The city of the user. Defaults to Unknown.
Name
zip_code
Type
string
Description
The ZIP or postal code. Defaults to Unknown.
Name
latitude
Type
float
Description
The geographical coordinate, latitude of user's geographical location. Defaults to -1 if unavailable.
Name
longitude
Type
string
Description
The geographical coordinate, longitude of user's geographical location. Defaults to -1 if unavailable.
Name
time_zone
Type
string
Description
The time zone of the user. Defaults to Unknown.
Name
utm_source
Type
string
Description
Identifies the source of your destination link traffic, if exists.
Name
utm_medium
Type
string
Description
Specifies the marketing medium used, e.g., email or social, if any.
Name
utm_campaign
Type
string
Description
Associates the click with a specific marketing campaign.
Name
utm_term
Type
string
Description
Captures specific terms related to the destination link.
Name
utm_content
Type
string
Description
Differentiates between similar content in a campaign.
Name
utm_referrer
Type
string
Description
Refers to the referring website, if available.
Name
utm_referrer_url
Type
string
Description
Captures the URL of the referring website.

Webhook Response

{
  "event": "action",
  "paylaod": {
      "campaign_id": "b332c73f-0645-4684-840d-ea1545bdb321",
      "referral_link_id": "1",
      "referrer_id": "abc@gmail.com",
      "referred_user_id": "referreduser@gmail.com",
      "action_type": "SUBSCRIPTION_PURCHASED",
      "referral_code": "4P4X67NWQ",
      "domain": "getwaitlist.com",
      "ip_address": "192.101.67.90",
      "timestamp": "2024-05-14T17:19:01.110260",
      "browser": "Chrome",
      "browser_version": "120.0.0",
      "engine": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "os": "iOS",
      "os_version": "Unknown",
      "device": "iPhone"
      "device_model": "Other",
      "device_vendor": "Apple",
      "bot": "False",
      "referer": "Direct",
      "referer_url": "Direct",
      "continent_name": "Europe",
      "country_code": "AT",
      "country_name": "Austria",
      "state_prov": "Lower Austria",
      "state_prov_code": "3",
      "city": "Gföhl",
      "zip_code": "Unknown",
      "latitude": -1,
      "longitude": -1,
      "time_zone": "Europe/Vienna",
      "state_prov_code": "3",
      "utm_source": "google",
      "utm_medium": null,
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": null,
      "utm_referrer": null,
      "utm_referrer_url": null,
  }
}

POST/[YOUR CONFIGURED URL]

Referral Event

The Webhook is triggered each time a successful referrral takes place, i.e. when createReferedUser runs successfully.

Properties

Name
event
Type
string
Description
When a successful referral takes place, the event will always be referral.
Name
payload
Type
object
Description
Payload containing all the data related to the referral that is created.

Payload Object

Name
campaign_id
Type
string
Description
The ID of the Campaign for which the referral is tracked.
Name
referral_link_id
Type
string
Description
The ID of the Referral Link for which referral is created.
Name
referrer_id
Type
string
Description
ID of the user to which the referral link belongs to, if any. Otherwise defaults to an empty string.
Name
referred_user_id
Type
string
Description
ID of the referred user.
Name
referral_code
Type
string
Description
Unique code associated with the referral link.
Name
ip_address
Type
string
Description
The IP address from which referral is created, i.e. IP address of referred user.
Name
timestamp
Type
string
Description
Serialized UTC timestamp of when the referral was created.
Name
browser
Type
string
Description
The user's browser that was used to create the referral. Defaults to Unknown.
Name
browser_version
Type
string
Description
The version of the user's browser that was used create the referral. Defaults to 0.0.0.
Name
engine
Type
string
Description
The user's agent string. Defaults to an empty string.
Name
os
Type
string
Description
The user's operating system. Defaults to Unknown.
Name
os_version
Type
string
Description
The user's operating system version. Defaults to Unknown.
Name
device
Type
string
Description
The type of device used to access the link. Defaults to Unknown.
Name
device_vendor
Type
string
Description
The brand of the user's device. Defaults to Unknown.
Name
device_model
Type
string
Description
The model of the user's device. Defaults to Unknown.
Name
continent_name
Type
string
Description
The name of the continent of the user. Defaults to Unknown.
Name
country_code
Type
string
Description
The code representing the country of the user. Defaults to Unknown.
Name
country_name
Type
string
Description
The name of the country. Defaults to Unknown.
Name
state_prov
Type
string
Description
The state or province name. Defaults to Unknown.
Name
state_prov_code
Type
string
Description
The code representing the state or province. Defaults to Unknown.
Name
city
Type
string
Description
The city of the user. Defaults to Unknown.
Name
zip_code
Type
string
Description
The ZIP or postal code. Defaults to Unknown.
Name
latitude
Type
float
Description
The geographical coordinate, latitude of user's geographical location. Defaults to -1 if unavailable.
Name
longitude
Type
string
Description
The geographical coordinate, longitude of user's geographical location. Defaults to -1 if unavailable.
Name
time_zone
Type
string
Description
The time zone of the user. Defaults to Unknown.

Webhook Response

{
  "event": "referral",
  "paylaod": {
      "campaign_id": "b332c73f-0645-4684-840d-ea1545bdb321",
      "referral_link_id": "1",
      "referrer_id": "abc@gmail.com",
      "referred_user_id": "referreduser@gmail.com",
      "referral_code": "4P4X67NWQ",
      "ip_address": "192.101.67.90",
      "timestamp": "2024-05-14T17:19:01.110260",
      "browser": "Chrome",
      "browser_version": "120.0.0",
      "engine": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "os": "iOS",
      "os_version": "Unknown",
      "device": "iPhone"
      "device_model": "Other",
      "device_vendor": "Apple",
      "continent_name": "Europe",
      "country_code": "AT",
      "country_name": "Austria",
      "state_prov": "Lower Austria",
      "state_prov_code": "3",
      "city": "Gföhl",
      "zip_code": "Unknown",
      "latitude": -1,
      "longitude": -1,
      "time_zone": "Europe/Vienna",
  }
}