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 will cover the more scalable approach via the use of webhooks.
Note: Implementing this will require technical expertise on your part
Setting up the custom reward
On the dashboard, go to Campaigns > All Campaigns > Select your campaign.
Go to Rewards then click the Advocate Reward tab.
Select the Custom reward option for your Advocate Reward.
Provide the webhook URL that you would like to use to our support team so that we can apply this for you on the backend. Please let support know that this is a webhook URL specifically for the custom reward.
When a referral is detected, the ReferralCandy system will call that webhook URL with a payload containing the details of that referral along with a signature for authentication.
Verify the authenticity of the payload by making a call to the ReferralCandy app with the signature.
Once the payload is verified, you have access to the data for that referral.
i.e. We return the following JSON response when a referred purchase is made:
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 an 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 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: Our server expects a response with HTTP status code of 200. If the webhook notification does not get a 200 response, the ReferralCandy app will send you an email to notify you about this. The webhook will not be tried again and the reward isn’t lost (this webhook is just a notification, so it will not affect the running of your referral program).
💬 Need help? Click the chat widget on the right to start a conversation. Learn more