With the web hook endpoints, you can subscribe and unsubscribe to events within your Referral Rock account. To subscribe and unsubscribe, call the endpoints respectively described here and here. the set of events supported is listed below. the sample included with each event is an example of the request body that will be sent with the post request to the endpoint specified.
Available events for Programs:
{
"Id": "00000000-0000-0000-0000-000000000000",
"IsActive": true,
"IsDefault": true,
"Name": "New Referrals Program",
"Type": "Web",
"Title": "New Referrals Program",
"MemberOffer": "Gift Card",
"ReferralOffer": "Another Gift Card",
"DirectUrl": "http://www.example.com",
"WidgetUrl": "http://widget.example.com",
"LoginUrl": "http://login.example.com",
"RegistrationViews": 0,
"MembersRegistered": 0,
"MemberViews": 0,
"ReferralViews": 0,
"ReferralsCreated": 0,
"ReferralsApproved": 0,
"MembersActive": 0,
"MembersDisabled": 0,
"ReferralsPending": 0,
"ReferralsQualified": 0,
"ReferralsDenied": 0,
"ReferralsApprovedAmount": 0.0,
"RewardsCreated": 0,
"RewardsPending": 0,
"RewardsIssued": 0,
"RewardsIssuedAmount": 0.0,
"Timestamp": 1668174706
}
{
"Id": "00000000-0000-0000-0000-000000000002",
"displayName": "Test Inc (example@site.com)",
"firstName": "firstName",
"lastName": "lastName",
"email": "example@site.com",
"phone": "",
"externalIdentifier": "",
"dateOfBirth": null,
"addressLine1": "",
"addressLine2": "",
"city": "",
"countrySubdivision": "",
"country": "",
"postalCode": "",
"disabledFlag": false,
"customOverrideURL": "",
"payoutInfo": null,
"customOption1Name": "",
"customOption1Value": "",
"customText1Name": "",
"customText1Value": "",
"customText2Name": "",
"customText2Value": "",
"programId": "00000000-0000-0000-0000-000000000000",
"programTitle": "Customer Referral Program",
"programName": "myprogram",
"referralUrl": "https://example/l/E14D26F4/",
"referralCode": "E14D26F4",
"memberUrl": ""https://example/l/E14D26F4/",
"emailShares": 0,
"socialShares": 0,
"views": 0,
"referrals": 0,
"lastShare": null,
"referralsApproved": 0,
"referralsQualified": 0,
"referralsPending": 0,
"referralsApprovedAmount": 0,
"rewardsPendingAmount": 0,
"rewardsIssuedAmount": 0,
"rewardAmountTotal": 0,
"rewards": 0,
"createDt": "2018-04-04T16:58:06.947Z",
"Timestamp": 1668174706
}
{
"Id": "00000000-0000-0000-0000-000000000002",
"DisplayName" : "Jane Doe (Jane@example.com)",
"FullName": "Jane Doe",
"FirstName": "Jane",
"LastName": "Doe",
"CompanyName": "Taco Inc.",
"Email": "Jane@example.com",
"ExternalId": "00000000-0000-0000-0000-000000000000",
"PhoneNumber": "888-555-1212",
"Amount": 0,
"PreferredContact": "Email Me",
"CreatedDate": "2016-04-10T18:46:21.3597347Z",
"ProgramId": "00000000-0000-0000-0000-000000000000",
"ProgramName": "New Referrals Program",
"ProgramTitle": "New Referrals Program",
"MemberId": "00000000-0000-0000-0000-0000000000001",
"MemberName": "Jon Doe",
"MemberEmail": "Jon@example.com",
"MemberReferralCode": "ABC12345",
"MemberExternalId": "123456789",
"ApprovedDate": "2016-04-10T18:46:21.3597347Z",
"QualifiedDate": "2016-04-10T18:46:21.3597347Z",
"Status": "Pending",
"UpdateDate": "2016-04-10T18:46:21.3597347Z",
"Note": "Note",
"PublicNote": "Public Note",
"AmountFormatted": "$0.00",
"CustomOption1Name": "",
"CustomOption2Name": "",
"CustomText1Name": "",
"CustomText2Name": "",
"CustomText3Name": "",
"CustomOption1Value": "",
"CustomOption2Value": "",
"CustomText1Value": "",
"CustomText2Value": "",
"CustomText3Value": "",
"ConversionNote": "",
"ConversionIPAddress": "",
"Timestamp": 1668174706
}
{
"Id": "00000000-0000-0000-0000-000000000000",
"PayoutId": "00000000-0000-0000-0000-000000000000",
"PayoutDescription": null,
"ProgramId": "00000000-0000-0000-0000-000000000000",
"ProgramName": null,
"MemberId": null,
"ReferralId": null,
"Type": null,
"RecipientId": null,
"RecipientName": null,
"RecipientEmailAddress": null,
"Status": null,
"Amount": 0.0,
"CreateDate": "0001-01-01T00:00:00",
"IssueDate": null,
"EligibilityDate": "0001-01-01T00:00:00",
"Description": null,
"TransactionID": "00000000-0000-0000-0000-000000000000",
"UpdateDate": "0001-01-01T00:00:00",
"ReferralDisplayName": null,
"Timestamp": 1668174706
}
{
"Message": "Email added to unsubcribed list for all email types",
"Email": "test123@google.com",
"eventName": "EmailUnsubscribed",
"Timestamp": 1668174706
}
Referral Rock will sign the webhook events it sends to your endpoints by including a signature in each event’s RR-Signature header. This allows you to verify that the events were sent by Referral Rock, not by a third party. You can verify signatures by using one of the following examples.
using System;
using System.Security.Cryptography;
using System.Text;
// Key that will be used to encrypt JSON body data and event type.
// Make sure the key used is the same key for the event type that is being handled.
string key = "Your Generated Key";
/*
Example JSON data that will be received
{payload}: needs to be replaced by the request payload received .
Example: {
"Id": "00000000-0000-0000-0000-000000000000",
"IsActive": true,
"IsDefault": true,
"Name": "New Referrals Program",
"Type": "Web",
"Title": "New Referrals Program",
"MemberOffer": "Gift Card",
"ReferralOffer": "Another Gift Card",
"DirectUrl": "http://www.example.com",
"WidgetUrl": "http://widget.example.com",
"LoginUrl": "http://login.example.com",
"RegistrationViews": 0,
"MembersRegistered": 0,
"MemberViews": 0,
"ReferralViews": 0,
"ReferralsCreated": 0,
"ReferralsApproved": 0,
"MembersActive": 0,
"MembersDisabled": 0,
"ReferralsPending": 0,
"ReferralsQualified": 0,
"ReferralsDenied": 0,
"ReferralsApprovedAmount": 0.0,
"RewardsCreated": 0,
"RewardsPending": 0,
"RewardsIssued": 0,
"RewardsIssuedAmount": 0.0,
"TimesStamp": 1668174706
}
{webhook_event}: webhook event (see the event list above)
*/
// Use body raw data
var payload = "< Your body raw data >";
// Concatenate payload JSON body raw data with webhook event to match
// the content that was used before encrypting the signature.
string content = "{payload}.{webhook_event}";
// Encrypt content using the SHA12 algorithm and convert it to a base 64 string.
byte[] keyByte = new ASCIIEncoding().GetBytes(key);
byte[] messageBytes = new ASCIIEncoding().GetBytes(content);
byte[] hashmessage = new HMACSHA512(keyByte).ComputeHash(messageBytes);
string base64Hashed = Convert.ToBase64String(hashmessage);
// Compare the encrypted data against the RR-Signature header.
// You can consider a valid request if the base64Hashed is equal to Request.Headers.GetValues("RR-Signature").First().
if(base64Hashed == Request.Headers.GetValues("RR-Signature").First())
{
//signature valid
}
Node Sample using express:
// libray responsible for encrypt body data + event type
var crypto = require('crypto');
// Example of how the express library handles the request.
app.post('/', (req, res) => {
// Key that will be used to encrypt JSON body data and event type.
// Make sure the key used is the same key for the event type that is being handled.
var key = 'Your generated key';
/*
Example JSON data that will be received
{payload}: needs to be replaced by the request payload received.
Example: {
"Id": "00000000-0000-0000-0000-000000000000",
"IsActive": true,
"IsDefault": true,
"Name": "New Referrals Program",
"Type": "Web",
"Title": "New Referrals Program",
"MemberOffer": "Gift Card",
"ReferralOffer": "Another Gift Card",
"DirectUrl": "http://www.example.com",
"WidgetUrl": "http://widget.example.com",
"LoginUrl": "http://login.example.com",
"RegistrationViews": 0,
"MembersRegistered": 0,
"MemberViews": 0,
"ReferralViews": 0,
"ReferralsCreated": 0,
"ReferralsApproved": 0,
"MembersActive": 0,
"MembersDisabled": 0,
"ReferralsPending": 0,
"ReferralsQualified": 0,
"ReferralsDenied": 0,
"ReferralsApprovedAmount": 0.0,
"RewardsCreated": 0,
"RewardsPending": 0,
"RewardsIssued": 0,
"RewardsIssuedAmount": 0.0,
"Timestamp": 1668174706
}
{webhook_event}: webhook event (see the event list above)
*/
// Get the JSON body raw data
var payload = request.body;
// Concatenate payload JSON body raw data with webhook event to match
// the content that was used before encrypting the signature.
var content = `${payload}.${webhook_event}`;
// Encrypt content using the SHA12 algorithm and convert it to a base 64 string.
var hmacSignature = crypto.createHmac('SHA512', Buffer.from(key, 'ASCII')).update(content).digest('base64');
// Compare the encrypted data against the RR-Signature header.
// You can consider a valid request if the hmaxSignature is equal to req.headers['RR-Signature'].
if(hmacSignature === req.headers['RR-Signature']){
//valid signature
}
})
JavaScript Sample
//Library used to encrypt body data & event type
var crypto = require("crypto");
//Replace key value here with your Webhook Key
var key = "rr_qXnAimw1krN8N1x8NFwA";
//Replace webhook event with matching webhook event
var webhook_event = "MemberUpdate";
//The value below should be taken from the 'RR-Signature' header in the request
var rr_signature =
"by+GqrfUnYywprmKYGkriH16DeAuKgN5o0xBqQ8nxTWzFLMRatWiPM/dsma1Ae0UkIkzn6XciVDCNCEAxQe4cg==";
//The value below should be the raw data from the JSON body
var payload =
'{"Id":"3dc6d74c-22ba-474e-88be-2aefe51eece1",' +
'"NewMemberId":null,' +
'"DisplayName":"Example Member (test@example.com)",' +
'"PayoutInfo":null,' +
'"PayoutInfos":null,' +
'"ProgramTitle":"My Referrals",' +
'"ProgramName":"Referral Program",' +
'"ReferralUrl":"https://example.referralrock.com/l/EXAMPLE1/",' +
'"MemberUrl":"https://example.referralrock.com/share/EXAMPLE2/",' +
'"EmailShares":0,' +
'"SocialShares":0,' +
'"Views":0,' +
'"Referrals":0,' +
'"ReferralsPending":0,' +
'"ReferralsQualified":0,' +
'"ReferralsApproved":0,' +
'"ReferralsApprovedAmount":0.0000,' +
'"RewardsPending":0.0000,' +
'"RewardsIssued":0.0000,' +
'"RewardAmountTotal":0.0000,' +
'"Rewards":0,' +
'"LastShare":null,' +
'"CreatedDate":"2024-03-20T15:31:30.233Z",' +
'"UpdateDate":"2024-03-20T15:35:17.093Z",' +
'"MemberViews":0,' +
'"LastMemberView":null,' +
'"LastReferralView":null,' +
'"Source":"AdminUI",' +
'"BlockSendingEmail":false,' +
'"BlockReason":"",' +
'"PrivateCode":"EXAMPLE2",' +
'"LastViewIPAddress":"",' +
'"AllowExcessPaymentsFlag":false,' +
'"WebConversionCount":null,' +
'"Timestamp":1710948918,' +
'"ExternalId":"",' +
'"ProgramId":"01e64205-5290-4b98-b21e-360a10c8672d",' +
'"ReferralCode":"EXAMPLE1",' +
'"FullName":"Example Member",' +
'"FirstName":"Example",' +
'"LastName":"Member",' +
'"Email":"test@example.com",' +
'"CustomReferralOverrideUrl":"",' +
'"CustomText1Name":"",' +
'"CustomOption1Name":"",' +
'"CustomText1Value":"",' +
'"CustomOption1Value":"",' +
'"CustomText2Name":"",' +
'"CustomText2Value":"",' +
'"DisabledFlag":false,' +
'"Password":"",' +
'"Phone":"",' +
'"AddressLine1":"",' +
'"AddressLine2":"",' +
'"City":"",' +
'"StateProvince":"",' +
'"Country":"",' +
'"ZipPostalCode":"",' +
'"BirthDate":null,' +
'"UtmSource":"",' +
'"UtmMedium":"",' +
'"UtmCampaign":"",' +
'"BrowserReferrerUrl":""}';
//Concatenate the payload JSON body raw data with webhook event to match
//the content that was used before encrypting the signature
var content = `${payload}.${webhook_event}`;
//Encrpyt content using the SHA12 algorithm and convert it to a base 64 string
var hmacSignature = crypto
.createHmac("SHA512", Buffer.from(key, "ASCII"))
.update(content)
.digest("base64");
if (hmacSignature === rr_signature) {
//signature is valid
console.log("Valid");
}
else {
//signature is invalid
console.log("Invalid");
}