Events Reference

Below are sample request payloads you will receive based on the webhook event types you have selected for your program.

PARTICIPANT_SUBMITTED_REWARD_FORM

Description: When a participant submits a reward form from the advocate portal

{
  "event": "PARTICIPANT_SUBMITTED_REWARD_FORM",
  "createdAt": 1558345202613,
  "data": {
    "id": "prfs_def678",
    "participantId": "x9a7uu",
    "participantEmail": "[email protected]",
    "rewardId": "crew_xlj123",
    "status": "UNREVIEWED",
    "formData": {
      "linkedinPostUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b"
    },  
    "participant": {
      "id": "x9a7uu",
      "email": "[email protected]",
      "firstName": "Richard",
      "lastName": "Hendricks",
      "notes": "",
      "rank": 9,
      "isWinner": true,
      "loyaltyActionCount": 11,
      "monthlyLoyaltyActionCount": 8,
      "prevMonthlyLoyaltyActionCount": 0,
      "createdAt": 1554431962667,
      "loyaltyActionSource": "DIRECT",
      "fraudRiskLevel": "LOW",
      "fraudReasonCode": "UNIQUE_IDENTITY",
      "metadata": {
        "piedPiperUserId": "12a39-8aajd-1dwiq",
        "companyName": "Pied Piper, Inc",
        "teamSize": "1-10"
      },
      "unsubscribed": false,
    },
    "reward": {
      "conversionsRequired": 1,
      "couponCode": "LI_25_GIFT",
      "createdAt": 1542560101404,
      "description": "Make a LinkedIn post mentioning Pied Piper",
      "subdescription": "Post must be less than 1 week old from date of submission",
      "instructions": "<div><p><strong>Helpful tips:</strong></p><ul><li>Talk about how you used to do things before using Pied Piper</li><li>Mention specific ROIs (e.g, time saved, revenue generated)</li></ul></div>",
      "cta": "Get $25",
      "submissionType": "URL",
      "submissionExampleUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b",
      "submissionFormUrl": "https://linkedin.com/shareArticle",
      "submissionFormFields": [
        {
          "key": "linkedinPostUrl",
          "label": "Your LinkedIn Post URL",
          "placeholder": "Enter your LinkedIn Post URL here",
          "type": "text",
          "isRequired": true,
          "isVisible": true
        }
      ],
      "submissionFormButtonText": "Submit",
      "submissionFormMessages": {
        "required": "is required",
        "reCaptchaRequired": "You must pass the reCAPTCHA verification.",
        "success": "Thanks! We have received your response.",
        "error": "There was an error. Please try submitting again.",
        "alreadySubmitted": "You already submitted this form."
      },      
      "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
      "limit": 1,
      "isUnlimited": true,
      "numberOfWinners": 3,
      "title": "LinkedIn Post Mention",
      "id": "crew_xlj123",
      "metadata": {
        "foo": "bar",
        "amount": "$25",
        "points": 1000
      }
    },
    "campaign": {
      "id": "ct8f71",
      "name": "Pied Piper Advocate Program",
      "currencyISO": "USD",
      "rewards": [
        {
          "id" : "crew_xlj123",        
          "title": "LinkedIn Post Mention",          
          "conversionsRequired": 1,
          "couponCode": "LI_25_GIFT",
          "description": "Make a LinkedIn post mentioning Pied Piper",
          "subdescription": "Post must be less than 1 week old from date of submission",
          "instructions": "<div><p><strong>Helpful tips:</strong></p><ul><li>Talk about how you used to do things before using Pied Piper</li><li>Mention specific ROIs (e.g, time saved, revenue generated)</li></ul></div>",
          "limit": 1,
          "isUnlimited": true,
          "limitDuration": "IN_TOTAL",
          "numberOfWinners": 3,
          "cta": "Get $25",
          "submissionType": "URL",
          "submissionExampleUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b",
          "submissionFormUrl": "https://linkedin.com/shareArticle",
          "submissionFormFields": [
            {
              "key": "linkedinPostUrl",
              "label": "Your LinkedIn Post URL",
              "placeholder": "Enter your LinkedIn Post URL here",
              "type": "text",
              "isRequired": true,
              "isVisible": true
            }
          ],
          "submissionFormButtonText": "Submit",
          "submissionFormMessages": {
            "required": "is required",
            "reCaptchaRequired": "You must pass the reCAPTCHA verification.",
            "success": "Thanks! We have received your response.",
            "error": "There was an error. Please try submitting again.",
            "alreadySubmitted": "You already submitted this form."
          },      
          "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
          "metadata": {
            "foo": "bar",
            "amount": "$25",
            "points": 1000
          }      
        }
      ]
    }
  }
}

---

PARTICIPANT_REACHED_A_GOAL

Description: When a participant unlocks a new reward

Important notes:

• If you have manual reward approval enabled for your program, events will be sent twice: (1) when the reward is pending approval and (2) when the reward is approved. To discern between unapproved/approved rewards, use the data.reward.approved property (approved rewards will have approved as true).

• The data.reward object contains combined data from the CampaignReward and ParticipantReward.

  • data.reward.rewardId represents the ID of the CampaignReward and will always be the same. You can find this ID from Program Editor > 1. Rewards and clicking the reward.

  • data.reward.id represents the ID of the ParticipantReward that was unlocked for the participant. This will be different for every new reward that the participant earns. You can find this ID by going to your admin dashboard and viewing the participant's rewards.

{
  "event": "PARTICIPANT_REACHED_A_GOAL",
  "createdAt": 1558345202613,
  "data": {
    "participant": {
      "id": "x9a7uu",
      "email": "[email protected]",
      "firstName": "Richard",
      "lastName": "Hendricks",
      "notes": "",
      "rank": 9,
      "isWinner": true,
      "loyaltyActionCount": 11,
      "monthlyLoyaltyActionCount": 8,
      "prevMonthlyLoyaltyActionCount": 0,
      "createdAt": 1554431962667,
      "loyaltyActionSource": "DIRECT",
      "fraudRiskLevel": "LOW",
      "fraudReasonCode": "UNIQUE_IDENTITY",      
      "metadata": {
        "piedPiperUserId": "12a39-8aajd-1dwiq",
        "companyName": "Pied Piper, Inc",
        "teamSize": "1-10"
      },
      "unsubscribed": false,
    },
    "reward": {
      "approved": true,
      "conversionsRequired": 1,
      "couponCode": "LI_25_GIFT",
      "createdAt": 1542560101404,
      "approvedAt": 1659474941892,
      "fulfilledAt": null,
      "description": "Make a LinkedIn post mentioning Pied Piper",
      "subdescription": "Post must be less than 1 week old from date of submission",
      "instructions": "<div><p><strong>Helpful tips:</strong></p><ul><li>Talk about how you used to do things before using Pied Piper</li><li>Mention specific ROIs (e.g, time saved, revenue generated)</li></ul></div>",
      "cta": "Get $25",
      "submissionType": "URL",
      "submissionExampleUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b",
      "submissionFormUrl": "https://linkedin.com/shareArticle",
      "submissionFormFields": [
        {
          "key": "linkedinPostUrl",
          "label": "Your LinkedIn Post URL",
          "placeholder": "Enter your LinkedIn Post URL here",
          "type": "text",
          "isRequired": true,
          "isVisible": true
        }
      ],
      "submissionFormButtonText": "Submit",
      "submissionFormMessages": {
        "required": "is required",
        "reCaptchaRequired": "You must pass the reCAPTCHA verification.",
        "success": "Thanks! We have received your response.",
        "error": "There was an error. Please try submitting again.",
        "alreadySubmitted": "You already submitted this form."
      },      
      "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
      "limit": 1,
      "isUnlimited": true,
      "numberOfWinners": 3,      
      "title": "LinkedIn Post Mention",
      "rewardId": "crew_xlj123",
      "id" : "prew_ccm2ue",
      "participantId": "x9a7uu",
      "metadata": {
        "foo": "bar",
        "amount": "$25",
        "points": 1000
      }
    },
    "campaign": {
      "id": "ct8f71",
      "name": "Pied Piper Advocate Program",
      "currencyISO": "USD",
      "rewards": [
        {
          "id" : "crew_xlj123",        
          "title": "LinkedIn Post Mention",          
          "conversionsRequired": 1,
          "couponCode": "LI_25_GIFT",
          "description": "Make a LinkedIn post mentioning Pied Piper",
          "subdescription": "Post must be less than 1 week old from date of submission",
          "instructions": "<div><p><strong>Helpful tips:</strong></p><ul><li>Talk about how you used to do things before using Pied Piper</li><li>Mention specific ROIs (e.g, time saved, revenue generated)</li></ul></div>",
          "limit": 1,
          "isUnlimited": true,
          "limitDuration": "IN_TOTAL",          
          "numberOfWinners": 3,          
          "cta": "Get $25",
          "submissionType": "URL",
          "submissionExampleUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b",
          "submissionFormUrl": "https://linkedin.com/shareArticle",
          "submissionFormFields": [
            {
              "key": "linkedinPostUrl",
              "label": "Your LinkedIn Post URL",
              "placeholder": "Enter your LinkedIn Post URL here",
              "type": "text",
              "isRequired": true,
              "isVisible": true
            }
          ],
          "submissionFormButtonText": "Submit",
          "submissionFormMessages": {
            "required": "is required",
            "reCaptchaRequired": "You must pass the reCAPTCHA verification.",
            "success": "Thanks! We have received your response.",
            "error": "There was an error. Please try submitting again.",
            "alreadySubmitted": "You already submitted this form."
          },      
          "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
          "metadata": {
            "foo": "bar",
            "amount": "$25",
            "points": 1000
          }      
        }
      ]
    }    
  }
}

---

NEW_PARTICIPANT_ADDED

Description: When a new participant is added to the program (via signups from the advocate portal, REST API, and manual adding/importing from the admin dashboard).

{
  "event": "NEW_PARTICIPANT_ADDED",
  "createdAt": 1558345215720,
  "data": {
    "id": "p88y0a",
    "email": "[email protected]",
    "firstName": "Gavin",
    "lastName": "Belson",
    "notes": "This is obviously our competitor trying out our product!",
    "rank": 762,
    "isWinner": false,
    "loyaltyActionCount": 1,
    "monthlyLoyaltyActionCount": 0,
    "prevMonthlyLoyaltyActionCount": 0,
    "createdAt": 1554479231190,
    "loyaltyActionSource": "DIRECT",
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTITY",    
    "loyaltyActionCountPerReward": {
    },
    "metadata": {
      "piedPiperUserId": "au71p-121x9-88faa",
      "companyName": "Hooli, Inc",
      "teamSize": "10,000+"
    },
    "unsubscribed": false,
    "campaign": {
      "id": "ct8f71",
      "name": "Pied Piper Advocate Program",
      "currencyISO": "USD",
      "rewards": [
        {
          "id" : "crew_xlj123",        
          "title": "LinkedIn Post Mention",          
          "conversionsRequired": 1,
          "couponCode": "LI_25_GIFT",
          "description": "Make a LinkedIn post mentioning Pied Piper",
          "subdescription": "Post must be less than 1 week old from date of submission",
          "instructions": "<div><p><strong>Helpful tips:</strong></p><ul><li>Talk about how you used to do things before using Pied Piper</li><li>Mention specific ROIs (e.g, time saved, revenue generated)</li></ul></div>",
          "limit": 1,
          "isUnlimited": true,
          "limitDuration": "IN_TOTAL",
          "numberOfWinners": 3,              
          "cta": "Get $25",
          "submissionType": "URL",
          "submissionExampleUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b",
          "submissionFormUrl": "https://linkedin.com/shareArticle",
          "submissionFormFields": [
            {
              "key": "linkedinPostUrl",
              "label": "Your LinkedIn Post URL",
              "placeholder": "Enter your LinkedIn Post URL here",
              "type": "text",
              "isRequired": true,
              "isVisible": true
            }
          ],
          "submissionFormButtonText": "Submit",
          "submissionFormMessages": {
            "required": "is required",
            "reCaptchaRequired": "You must pass the reCAPTCHA verification.",
            "success": "Thanks! We have received your response.",
            "error": "There was an error. Please try submitting again.",
            "alreadySubmitted": "You already submitted this form."
          },      
          "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
          "metadata": {
            "foo": "bar",
            "amount": "$25",
            "points": 1000
          }      
        }
      ]
    }    
  }
}

---

PARTICIPANT_FRAUD_STATUS_UPDATED

Description: When an existing participant's fraud status changes.

This webhook event is emitted if you manually mark a participant as a fraudster or non-fraudster from the LoyaltySurf admin dashboard. Learn more here.

Here is an example of a PARTICIPANT_FRAUD_STATUS_UPDATED event where you can check the participant's fraud status via data.participant.fraudRiskLevel (it will be one of the following options: "LOW", "MEDIUM", or "HIGH"). You can also check the fraud reason code via data.participant.fraudReasonCode (see the Participant object for all fraud reason code options).

{
  "event": "PARTICIPANT_FRAUD_STATUS_UPDATED",
  "createdAt": 1558345215720,
  "data": {
    "participant": {
      "id": "p88y0a",
      "email": "[email protected]",
      "firstName": "Gavin",
      "lastName": "Belson",
      "notes": "This is obviously our competitor trying out our product!",
      "rank": 762,
      "isWinner": false,
      "loyaltyActionCount": 1,
      "monthlyLoyaltyActionCount": 0,
      "prevMonthlyLoyaltyActionCount": 0,
      "createdAt": 1554479231190,
      "loyaltyActionSource": "DIRECT",
      "fraudRiskLevel": "LOW",
      "fraudReasonCode": "UNIQUE_IDENTITY",    
      "loyaltyActionCountPerReward": {
      },
      "metadata": {
        "piedPiperUserId": "au71p-121x9-88faa",
        "companyName": "Hooli, Inc",
        "teamSize": "10,000+"
      },
      "unsubscribed": false,
    },
    "campaign": {
      "id": "ct8f71",
      "name": "Pied Piper Advocate Program",
      "currencyISO": "USD",
      "rewards": [
        {
          "id" : "crew_xlj123",        
          "title": "LinkedIn Post Mention",          
          "conversionsRequired": 1,
          "couponCode": "LI_25_GIFT",
          "description": "Make a LinkedIn post mentioning Pied Piper",
          "subdescription": "Post must be less than 1 week old from date of submission",
          "instructions": "<div><p><strong>Helpful tips:</strong></p><ul><li>Talk about how you used to do things before using Pied Piper</li><li>Mention specific ROIs (e.g, time saved, revenue generated)</li></ul></div>",
          "limit": 1,
          "isUnlimited": true,
          "limitDuration": "IN_TOTAL",
          "numberOfWinners": 3,              
          "cta": "Get $25",
          "submissionType": "URL",
          "submissionExampleUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b",
          "submissionFormUrl": "https://linkedin.com/shareArticle",
          "submissionFormFields": [
            {
              "key": "linkedinPostUrl",
              "label": "Your LinkedIn Post URL",
              "placeholder": "Enter your LinkedIn Post URL here",
              "type": "text",
              "isRequired": true,
              "isVisible": true
            }
          ],
          "submissionFormButtonText": "Submit",
          "submissionFormMessages": {
            "required": "is required",
            "reCaptchaRequired": "You must pass the reCAPTCHA verification.",
            "success": "Thanks! We have received your response.",
            "error": "There was an error. Please try submitting again.",
            "alreadySubmitted": "You already submitted this form."
          },      
          "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
          "metadata": {
            "foo": "bar",
            "amount": "$25",
            "points": 1000
          }      
        }
      ]
    }    
  }
}

---

CAMPAIGN_ENDED

Description: When the program ends.

Please note: Only the first 1,000 will be returned in the winners Array.

{
  "event": "CAMPAIGN_ENDED",
  "createdAt": 1558345152138,
  "data": {
    "id": "ct8f71",
    "name": "Pied Piper Advocate Program",
    "participantCount": 5661,
    "startedAt": 1522432573250,
    "endedAt": 1533532422153,
    "status": "COMPLETE",
    "loyaltyActionCount": 1673,
    "winnerCount": 1673,
    "winners": [
      {
        "id": "x9a7uu",
        "email": "[email protected]",
        "firstName": "Richard",
        "lastName": "Hendricks",
        "notes": "",
        "rank": 9,
        "isWinner": true,
        "loyaltyActionCount": 11,
        "monthlyLoyaltyActionCount": 8,
        "prevMonthlyLoyaltyActionCount": 0,
        "createdAt": 1554431962667,
        "loyaltyActionSource": "DIRECT",
        "fraudRiskLevel": "LOW",
        "fraudReasonCode": "UNIQUE_IDENTITY",        
        "metadata": {
          "piedPiperUserId": "12a39-8aajd-1dwiq",
          "companyName": "Pied Piper, Inc",
          "teamSize": "1-10"
        },
        "unsubscribed": false,
      }
    ],
    "rewards": [
      {
        "id" : "crew_xlj123",        
        "title": "LinkedIn Post Mention",          
        "conversionsRequired": 1,
        "couponCode": "LI_25_GIFT",
        "description": "Make a LinkedIn post mentioning Pied Piper",
        "subdescription": "Post must be less than 1 week old from date of submission",
        "instructions": "<div><p><strong>Helpful tips:</strong></p><ul><li>Talk about how you used to do things before using Pied Piper</li><li>Mention specific ROIs (e.g, time saved, revenue generated)</li></ul></div>",
        "limit": 1,
        "isUnlimited": true,
        "limitDuration": "IN_TOTAL",
        "numberOfWinners": 3,
        "cta": "Get $25",
        "submissionType": "URL",
        "submissionExampleUrl": "https://linkedin.com/posts/sarah_s-my-review-of-pied-piper-8195769799870726145-Sr9b",
        "submissionFormUrl": "https://linkedin.com/shareArticle",
        "submissionFormFields": [
          {
            "key": "linkedinPostUrl",
            "label": "Your LinkedIn Post URL",
            "placeholder": "Enter your LinkedIn Post URL here",
            "type": "text",
            "isRequired": true,
            "isVisible": true
          }
        ],
        "submissionFormButtonText": "Submit",
        "submissionFormMessages": {
          "required": "is required",
          "reCaptchaRequired": "You must pass the reCAPTCHA verification.",
          "success": "Thanks! We have received your response.",
          "error": "There was an error. Please try submitting again.",
          "alreadySubmitted": "You already submitted this form."
        },      
        "imageUrl": "https://res.cloudinary.com/loyaltysurf/image/upload/v1553218876/production/ls8shgq3qlwldljr8tl2.jpg",
        "metadata": {
          "foo": "bar",
          "amount": "$25",
          "points": 1000
        }      
      }
    ]
  }
}