Web Hooks


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:
  • ProgramAdd
  • ProgramUpdate
    (*sent only on activation change)
  • ProgramDelete
Available events for Members:
  • MemberAdd
  • MemberUpdate
  • MemberDelete
Available events for Referrals:
  • ReferralAdd
  • ReferralUpdate
    (*sent on any change including status change)
  • ReferralDelete
  • ReferralStatusChange
Available events for Rewards:
  • RewardAdd
  • RewardUpdate
  • RewardDelete
  • RewardIssue
Available events for Emails:
  • EmailUnsubscribed

Event Details

ProgramAdd, ProgramUpdate, ProgramDelete

Sample:
{
    "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
}
                

MemberAdd, MemberUpdate, MemberRemove

Sample:
        {
            "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
        }
                

ReferralAdd, ReferralUpdate, ReferralStatusChange, ReferralDelete

Sample:
{
    "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
}
                

RewardAdd, RewardUpdate, RewardIssue, RewardDelete

Sample:
{
    "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
}
                

EmailUnsubscribed

Sample:
      {
            "Message": "Email added to unsubcribed list for all email types",
            "Email": "test123@google.com",
            "eventName": "EmailUnsubscribed",
            "Timestamp": 1668174706
        }
                

Check the webhook signatures

Verify the events that Referral Rock sends to your webhook endpoints.


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.

C# Sample using webapi:
                    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
                        }
                    })