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).

  • 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).

{
  "event": "PARTICIPANT_REACHED_A_GOAL",
  "createdAt": 1558345202613,
  "data": {
    "participant": {
      "id": "x9a7uu",
      "email": "richard@piedpiper.com",
      "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"
      }
    },
    "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": "gavin.belson@hooli.com",
    "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": "richard@piedpiper.com",
      "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"
      }
    },
    "metadata": {
      "piedPiperUserId": "au71p-121x9-88faa",
      "companyName": "Hooli, Inc",
      "teamSize": "10,000+"
    }
  }
}

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": "richard@piedpiper.com",
        "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"
        }
      }
    ]
  }
}

Last updated