Using a webhook to receive Custom Reward notifications for referred purchases, you can receive a payload of information every time ReferralCandy successfully detects a referred purchase.
Alternatively, you can process this information manually as we'll send you an email each time a referral is detected. However, this guide covers a more scalable approach with webhooks.
Note: The steps outlined in this article require technical expertise. ReferralCandy doesn't support troubleshooting issues with custom code.
Set up the custom reward
On the dashboard, go to Campaigns > Select your campaign.
Go to Rewards then click the Advocate Reward tab.
Select the Custom reward option.
Provide the webhook URL that you'd like to use to our support team so that we can apply this for you on the backend. Let support know that this is a webhook URL specifically for the Custom reward.
When a referral is detected, the ReferralCandy system calls that webhook URL with a payload containing the details of that referral along with a signature for authentication.
Using a webhook
When a referred purchase is made, the following JSON response is returned:
Field : Description
referral_email : Email address of referred friend.
referral_timestamp : UNIX timestamp when referral purchase was made.
referring_email : Email address of referring Advocate.
Example of the JSON response:
{
"referral_email": "friend@example.com",
"referral_timestamp": 1434439382,
"referring_email": "advocate@example.com"
}
Each webhook notification includes the HTTP_X_REFERRAL_CANDY_SIGNATURE header, which is generated by calculating the MD5 hash of your API secret along with the data sent in the request. To verify the authenticity of a webhook notification, calculate the MD5 hash and ensure that it matches the value of the HTTP_X_REFERRAL_CANDY_SIGNATURE header.
Note that if you are using a Rack-based framework such as Ruby on Rails or Sinatra, the header you are looking for is HTTP_X_REFERRAL_CANDY_SIGNATURE.
A Ruby example:
require 'digest/md5'
# obtain from your ReferralCandy My Profile page
API_SECRET = "your_secret"
def webhook_verified?(request)
data = request.body.read
signature = Digest::MD5.hexdigest("#{API_SECRET}#{data}")
signature == request.env["HTTP_X_REFERRAL_CANDY_SIGNATURE"]
end
Note: The ReferralCandy server expects a response with HTTP status code of 200. If the webhook notification does not get a 200 response, the ReferralCandy app sends you an email to notify you. The webhook will not be tried again and the reward isn’t lost. This webhook is just a notification and won't affect your referral program.
💬 Need help? Click the chat widget on the right to start a conversation. Learn more