Events Reference

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

PARTICIPANT_REACHED_A_GOAL

Description: When a participant unlocks a new reward

Important notes:

• For double-sided rewards, two events will be sent for both referrer and referee. To discern between the two, use the data.reward.isReferrer property (the referrer will have isReferrer as true).

  • You can confirm this by examining data.reward.referrerId and data.reward.referredId and comparing it with data.participant.id.

• If you have manual reward approval enabled for your campaign, 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 Campaign 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": "[e-mail]",
      "firstName": "Richard",
      "lastName": "Hendricks",
      "notes": "",
      "rank": 9,
      "isWinner": true,
      "referralCount": 11,
      "monthlyReferralCount": 8,
      "prevMonthlyReferralCount": 0,
      "shareUrl": "http://piedpiper.com?grsf=x9a7uu",
      "impressionCount": 309,
      "uniqueImpressionCount": 285,
      "inviteCount": 285,
      "shareCount": 163,
      "createdAt": 1554431962667,
      "referralSource": "DIRECT",
      "fraudRiskLevel": "LOW",
      "metadata": {
        "piedPiperUserId": "12a39-8aajd-1dwiq",
        "companyName": "Pied Piper, Inc",
        "teamSize": "1-10"
      },
      "unsubscribed": false,
    },
    "reward": {
      "approved": true,
      "conversionsRequired": 1,
      "couponCode": "PROMO_20_OFF",
      "createdAt": 1542560101404,
      "approvedAt": 1659474941892,
      "fulfilledAt": null,
      "description": "Win a free t-shirt when you refer a friend to sign up to Pied Piper!",
      "imageUrl": "https://res.cloudinary.com/growsurf/image/upload/v1553218876/development/ls8shgq3qlwldljr8tl2.jpg",
      "limit": 3,
      "title": "Early-Bird Reward",
      "isReferrer": true,
      "type": "SINGLE_SIDED",
      "rewardId": "xlj123",
      "id": "ccm2ue",
      "referredId": "ad3dfa",
      "referrerId": "x9a7uu",
      "metadata": {
        "foo": "bar",
        "amount": "$25",
        "points": "1000"
      }
    }
  }
}

---

NEW_PARTICIPANT_ADDED

Description: When a new participant is added to the campaign (includes direct signups, referrals, and participants added/imported via dashboard).

{
  "event": "NEW_PARTICIPANT_ADDED",
  "createdAt": 1558345215720,
  "data": {
    "id": "p88y0a",
    "email": "[e-mail]",
    "firstName": "Gavin",
    "lastName": "Belson",
    "notes": "This is obviously our competitor trying out our product!",
    "rank": 762,
    "isWinner": false,
    "shareUrl": "http://piedpiper.com?grsf=p88y0a",
    "referralCount": 0,
    "monthlyReferralCount": 0,
    "prevMonthlyReferralCount": 0,
    "impressionCount": 0,
    "uniqueImpressionCount": 0,
    "inviteCount": 0,
    "shareCount": 3,
    "createdAt": 1554479231190,
    "referralSource": "PARTICIPANT",
    "fraudRiskLevel": "LOW",
    "referredBy": "x9a7uu",
    "referrer": {
      "id": "x9a7uu",
      "email": "[e-mail]",
      "firstName": "Richard",
      "lastName": "Hendricks",
      "notes": "",
      "rank": "9",
      "isWinner": true,
      "referralCount": 11,
      "monthlyReferralCount": 8,
      "shareUrl": "http://piedpiper.com?grsf=x9a7uu",
      "impressionCount": 309,
      "uniqueImpressionCount": 285,
      "inviteCount": 285,
      "shareCount": 163,
      "createdAt": 1554431962667,
      "referralSource": "PARTICIPANT",
      "fraudRiskLevel": "LOW",
      "metadata": {
        "piedPiperUserId": "12a39-8aajd-1dwiq",
        "companyName": "Pied Piper, Inc",
        "teamSize": "1-10"
      },
      "unsubscribed": false,
    },
    "metadata": {
      "piedPiperUserId": "au71p-121x9-88faa",
      "companyName": "Hooli, Inc",
      "teamSize": "10,000+"
    },
    "unsubscribed": false,
  }
}

---

CAMPAIGN_ENDED

Description: When the campaign ends.

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

{
  "event": "CAMPAIGN_ENDED",
  "createdAt": 1558345152138,
  "data": {
    "id": "ct8f71",
    "name": "Middle-Out Compression Launch",
    "participantCount": 5661,
    "startedAt": 1522432573250,
    "endedAt": 1533532422153,
    "status": "COMPLETE",
    "impressionCount": 11075,
    "referralCount": 1673,
    "winnerCount": 1673,
    "winners": [
      {
        "id": "x9a7uu",
        "email": "[e-mail]",
        "firstName": "Richard",
        "lastName": "Hendricks",
        "notes": "",
        "rank": 9,
        "isWinner": true,
        "referralCount": 11,
        "monthlyReferralCount": 8,
        "prevMonthlyReferralCount": 0,
        "shareUrl": "http://piedpiper.com?grsf=x9a7uu",
        "impressionCount": 309,
        "uniqueImpressionCount": 285,        
        "shareCount": 163,
        "createdAt": 1554431962667,
        "referralSource": "PARTICIPANT",
        "fraudRiskLevel": "LOW",
        "metadata": {
          "piedPiperUserId": "12a39-8aajd-1dwiq",
          "companyName": "Pied Piper, Inc",
          "teamSize": "1-10"
        },
        "unsubscribed": false,
      }
    ]
  }
}