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
Go to your campaign's Advocate reward page:
Select a reward tier to Edit.
Select the Custom reward option.
Save the changes.
Contact support and provide the webhook URL that you'd like to use. Let support know that this is a webhook URL specifically for the Custom reward.
When a referral is detected, the 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