Webhooks And Referral Factory: A Full Guide

A webhook is a way for different software applications to talk to each other in real-time. With Referral Factory, you can use webhooks to send referred leads, trigger a qualification, or issue a reward.

RF_visual1-png

In this guide πŸ‘‡

πŸ‘‰ Why Use Webhooks?

πŸ‘‰ Outbound Webhook

πŸ‘‰ Inbound Webhook

πŸ‘‰ How Do You Send The Referred Users Code OUT

Why Use Webhooks?

There are two reasons πŸ‘‡

  • Every time you get a new referred user (or a new lead) you want to send that user to your already existing business workflows.

  • You would want to send the code/coupon back to Referral Factory to qualify a user.


First, you'll need to build your referral program using the campaign builder inside Referral FactoryOnce your referral program is up and running, you can then use webhooks to send and receive the data. 

There are two types of webhooks πŸ‘‡

πŸ‘‰ Outbound Webhook

πŸ‘‰ Inbound Webhook


1. Outbound Webhook

In the case of Referral Factory, you can create an outbound webhook to send the data of your new referred user (or referred lead) to any endpoint – this could be an endpoint your developer creates or an endpoint you create in Zapier,  Airtable, Tray.io, or anywhere else that can receive an incoming webhook. 

Once you have created your webhook endpoint that can receive the data you're trying to send out, 

πŸ‘‰ Navigate to your campaigns tab in your dashboard

πŸ‘‰ Click on the Actions dropdown

πŸ‘‰ Choose Webhooks 

Screenshot 232023-03-13 at 17-07-05-png

πŸ‘‰ Click on the "Create An Outbound Webhook" button. 

555

πŸ‘‰ Choose An Event

Follow the step-by-step prompts – start by choosing the event that your Webhook should fire on. 

2222

πŸ‘‰ Users To Send
Select which users to send. In most cases, you only want to send the referred user's data out, as these are the new users that have been referred to you.
Screenshot 2023-03-13 at 17-50-54-png-1

πŸ‘‰ Endpoint & Method

  1. Next, you will need to enter the endpoint that you created earlier. This must be a URL starting with https.
  2. You will then choose the request type – in most cases you will choose β€œSend me POST Request”.
  • GET- It requests data from a specified resource.
  • POST- It submits the processed data to a specified resource.

Screenshot 2023-03-13 at 18-09-45-png

πŸ‘‰ User Fields

Next, you need to customize the request fields and choose what information you want to send through. Toggle on which request fields you would like to pass on. Remember you need to use the same naming convention as your endpoint in order to catch the data correctly. For example – if you have named the field email_address in Airtable, you need to make sure you name it email_address in your Webhook setup on Referral Factory.

Screenshot 2023-03-13 at 17-57-21-png

πŸ‘‰ Hidden Fields

Next, you can use hidden fields if needed.

Screenshot 2023-03-13 at 18-05-50-png

πŸ‘‰ Headers

Next, you can set up your webhook headers (not required).

Screenshot eee2023-03-13 at 18-07-02-png

πŸ‘‰ Finish

Once you’ve completed the above steps, make sure you give your Webhook a name that you can easily identify and click β€˜Save’.

Screenshot for 2023-03-13 at 18-11-40-png

Congrats. Your Webhook is now setup πŸ™Œ

Once you have created your Webhook or Webhooks, you can find them by navigating to your campaigns tab β†’ clicking the blue 'Actions' button β†’ and then clicking on Webhooks πŸ‘‡

Screenshot 2023-03-13 at 18-14-11-png

Here is an example of how the request body is formatted in the request when data is sent to your endpoint. Data is sent via query parameters to your Webhook URL. 

referrer_id=261470&referrer_code=zgLAYb&referrer_first_name=Jessica&referrer_email=support%2Bjessica%40referral-factory.com&id=261471&code=zruTPh&first_name=Byron&email=support%2Bbyron%40referral-factory.com&url=https%3A%2F%2Fwebhooks.referral-factory.com%2FzruTPh%2Fjoin&source=Referred&date=2022-06-09&referrals_count=0&campaign_id=4815

Referral Factory - example of a webhook format-png

Read more about the Outbound Webhook in this help guide. 

2. Inbound Webhook

You can use an inbound webhook to allow you to easily qualify your referred users when they convert - simply by sending their unique code to your inbound webhook endpoint. 

 

We created an inbound webhook so that you can easily qualify your referred users once they convert. You do this by sending their unique code to the endpoint given to you in your account. To find your inbound webhook endpoint:

πŸ‘‰ going to the SETTINGS tab

πŸ‘‰ scrolling down to the webhook section.

Screenshot 2023-03-13 at 18-57-46-png

Hit SHOW to see your webhook endpoint, and please remember to keep this endpoint URL private. 

Screenshot 442023-03-13 at 18-57-46-png-1

You can automatically update the status of a referred user by sending their unique code to this endpoint, which means you will be changing this:  

 

Qualified = No 

to 

Qualified = Yes

Referral Factory Qualifying Referrals -png

Below is an example of the payload you would use πŸ‘‡

    curl "https://referral-factory.com/webhook/{token}/qualify" \
-X POST \
-d "code={code}"

 

Please Note: In order to use the inbound webhook to qualify a referred user, you need to make sure you first send the new referred user's CODE out when they join the campaign. This means that when a new "referred user" joins your campaign, you capture that user's CODE in your own software application or CRM. Once you've captured the code, you can then send it back (using the inbound webhook), when that referred user qualifies.

 

Referral Factory Qualifying Referrals-png

How Do You Send The Referred Users Code OUT

 

In order to qualify a referred user using their code, you first need to have that user's code in your system or workflow. Below we'll show you the methods you can use to get a user code OUT of Referral Factory, right when they join your campaignπŸ‘‡

 

  • Create an outbound Webhook to fire every time a new referred user joins your campaign - this will send the CODE with the user into your system. Read our help guide on how to do this here.
  • Set up the 'New User' Zap to fire every time a new referred user joins your campaign - this will send the CODE with the user to Zapier, and from Zapier you can send it to your system. Read our help guide on how to do this here
  • Using one of our native CRM integrations, you can send all your new referred users over to your CRM as they join your campaign, passing along their CODES. We offer integrations with many CRMS, but here is an example of how to do that using HubSpot
  • Using the redirect option which you can select on step 3 of your campaign builder. This allows you to redirect the invited users off to your own website once they have joined the campaign, and pass along their CODE as a GET parameter in the URL we direct them to. Read our help guide on how to do this here
  • Using the API you can call any direct or referred user by using the 'Get A Specific User' function of our API, you can then view all the information for that user including their code. Read our API documentation on this function here

Learn more about Outbound Webhooks.

Learn more about Inbound Webhooks.