This is the developer reference for the custom-reward webhook — the payload ReferralCandy sends, how to verify it, and what your endpoint should return. For what a custom reward is, when to use one, and a plain-language overview of what setting up a webhook involves, see Advocate Reward: Custom.
Once Custom is selected as your campaign's advocate reward and you've let us know the webhook URL to use, ReferralCandy calls that URL with the referral's details and a signature for authentication every time a referral is detected.
Note: Setting up and handling a webhook involves development work on your side. ReferralCandy can't troubleshoot custom code or your own integration.
The webhook payload
When a referred purchase is detected, ReferralCandy sends a JSON payload to your URL with these fields:
Field | Description |
| Email address of the referred friend. |
| UNIX timestamp of when the referred purchase was made. |
| Email address of the referring advocate. |
Example payload:
{
"referral_email": "friend@example.com",
"referral_timestamp": 1434439382,
"referring_email": "advocate@example.com"
}Verifying the webhook signature
Each webhook notification includes the HTTP_X_REFERRAL_CANDY_SIGNATURE header — an MD5 hash of your API secret combined with the data sent in the request. To confirm a notification really came from ReferralCandy, calculate the same MD5 hash and check that it matches the value of the HTTP_X_REFERRAL_CANDY_SIGNATURE header.
Get your API secret from Account > Profile in your ReferralCandy dashboard, under API Tokens — it's the API Secret ID field.
If you're using a Rack-based framework such as Ruby on Rails or Sinatra, the header is exposed as HTTP_X_REFERRAL_CANDY_SIGNATURE.
A Ruby example:
require 'digest/md5'
# obtain from Account > Profile > API Tokens (API Secret ID)
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: ReferralCandy expects your endpoint to respond with HTTP status code 200. If it doesn't, ReferralCandy emails you to let you know — the webhook isn't retried, but the reward isn't lost. The webhook is only a notification and doesn't affect your referral program.