FirstPromoter offers the flexibility to set up various types of rewards for your promoters, so you can motivate them in a personalized way.
However, apart from monetary rewards, you need to make these rewards visible within your application and attribute them to your users' accounts. This can be achieved using First Promoter's Webhooks feature, which sends notifications to your server whenever a promoter is created, earns rewards, or payments are made.
Step 1: Add Webhook URL
Navigate to your profile in the upper-right corner and select Settings.
Proceed to the Integrations tab and select +Add webhook.
Enter your Webhook URL and choose the desired campaign.
Save the webhook.
Step 2: Assign Customer/User ID to Promoters
Note: This step can be skipped if you use the API to create promoters. More details here.
Grab the promoter page link from the First Promoter campaigns section.
Create a function to append your logged-in user/customer ID from your system to that link as the "cust_id" query parameter.
Example URL with appended parameters: https://mysubdomain.firstpromoter.com?email=john%40email.com&referral_id=john&promo_code=JOHN30&first_name=John&cust_id=34254
You can see that you can append multiple fields to that url which will pre-fill the promoter sign up fields - a good way to reduce friction. The most important is "cust_id" parameter though.
Generate this link and place it on your app dashboard or other visible areas for your users. You can call it "Refer a friend and get 1 free month" as an example.
When your users sign up to the referral program, the "cust_id" parameter will be passed along and we'll have a way to match the promoter details from webhooks to your customer.
Step 3: Create Logic to Handle Webhooks
Depending on your campaign settings, you can handle one or two types of webhooks:
A) One-Sided, Non-Monetary Rewards (for Promoter Only)
Only the "fulfilment_pending" webhook is needed here:
Check the payload format of fulfilment_pending webhook.
Create the procedure in your system to handle the webhook call with a condition to execute only if the event type from the payload is "fulfilment_pending"
Use the "cust_id"(which was passed on promoter sign up) value from the webhook to find the user/customer to reward and apply the reward. You also have an "amount" value in case you set different rewards for different campaigns or promotions.
Note: It's up to you how you apply the rewards to the users, for example, for Stripe you can apply a negative invoice item or a 100% discount code to the Stripe invoice in order to give a free month.
B) Two-Sided, Non-Monetary Rewards (for Promoter and Referred Person)
For this, you need "lead_signup" and "fulfilment_pending" webhooks.
First we will handle "lead_signup" to apply the offer to promoter "friend", the person referred by the promoter:
Check the payload format for lead_signup webhook.
Create a procedure in your system to handle the webhook call with a condition to execute only if the event type from the payload is "lead_signup".
Check if promotion['status'] is equal to "offer_running", otherwise exit/return(skip to step 6)
Use the "uid" or "email" value to find the user in your system.
Apply the offer to your user. promotion['current_offer'] JSON can give you more information about the offer to apply, including amount and unit/type.
Return a 2xx status code if the everything is successful. Something else to retry the webhook later.
Now we will handle "fulfilment_pending" to apply the reward to the promoter:
Check the payload format for fulfilment_pending webhook.
Create the procedure in your system to handle the webhook call with a condition to execute only if the event type from the payload is "fulfilment_pending"
Use the "cust_id"(which was passed on promoter sign up) value from the webhook to find the user/customer to reward and apply the reward. You also have an "amount" value in case you set different rewards for different campaigns or promotions.
Note: It's up to you how you apply the rewards to the users, for example, for Stripe you can apply a negative invoice item or a 100% discount code to the Stripe invoice in order to give a free month.
Return a 200 status code if everything is successful. Return 2xx(except 200), to skip the fulfilment(it will remain in pending state) and other status in case of error/you want the webhook to be retried later.
Additional Notifications:
When a promoter signs up and is accepted to a campaign, it sends a promoter_accepted notification.
When a lead signs up for trial, it sends a lead_signup notification. This is mostly used when you give and offer like free credits to the user who was referred by a promoter.
When a reward is attributed to a promoter, it sends a reward_created notification.
When a reward is approved and sent to fulfilments, it sends a fulfilment_pending notification.
When a fulfilment is marked as completed, it sends a fulfilment_completed notification.
If some of the webhooks are not fired, it means they are probably disabled for your account and you need to contact us to enable them.