Webhooks

In the standard integration of the Pilgrim SDK, the SDK will call your app with a notification that your user has arrived at a place. From there, it is likely that you will take some/all of the pieces of information that are handed to you and send those up to your servers for logging or other actions like notification sending. This is a good flow for most apps, but does require the upfront work of defining the client/server protocol to get this information up from your application. To get around this, Foursquare offers the ability to have your servers called anytime one of your user arrives at a place.

Some possible benefits:

  • Reduced mobile network traffic and potential battery savings for your users via cutting out an API request to your servers from the device.
  • Faster development iteration on your side without having to deploy a new app version.
  • Allows Foursquare to potentially offer new data to you without requiring an app or SDK update.

Important: Webhooks get triggered in addition to the regular callback in the SDK and don’t alter SDK behavior at all.


Setup

From your Pilgrim Console, click on the Webhooks tab and input your webhook URL:

For each arrival, departure, and geofence event, we will send a POST request with details about the event. We will also include the secret key provided in your Pilgrim Console so you know it’s us.


Payload

The following is the payload structure for version 2 of the webhook. If you are still on version 1, you will find webhook v1 documentation, which contains instructions for updating.

The notification will come to your server endpoint as an application/json POST request. Examples are available below.

Headers

Param Value  
Content-Length Integer Size of body content in bytes. Example: 708
Content-Type String Will be: application/json
Pilgrim-Secret String A unique string that will be included on every request. You can find your secret in the developer console on the Pilgrim page.
User-Agent String The payload’s user agent will now be: Foursquare-PilgrimSDK/$version. Example: Foursquare-PilgrimSDK/2.0
X-Forwarded-For IP Address Example: 199.38.179.113
X-Forwarded-Proto String Example: https

Body

Param Value  
pilgrimVisitId String The unique ID of the visit. Required for confirming visits back to Foursquare
eventType String The type of notification that is coming through: placeArrival, placeDeparture, placeHistorical.
timestamp long Time of the event in milliseconds since epoch
placeEvent JSON Hash Contains the venue and event information about the visit
lat Double The latitude of the user when they arrived at the place
lng Double The longitude of the user when they arrived at the place
user JSON Hash In the SDK, there is a property available for you to set called userInfo. This is a set of arbitrary parameters that you set on the SDK that will then be passed through to your endpoint here. For example, if you set a map of “userId” -> “123456” in the SDK, the request to your server you would also see a parameter of “userId”. The arbitrary params should be set before starting the SDK.
sdkType String The SDK that generated the notification iossdk or androidsdk

placeEvent

Key Type Description  
venues Array<Venue> The place the user is at. Currently a max of 1 item is sent.  
arrivalTime long Time of the arrival in milliseconds since epoch  
departureTime (Optional) long Time of the departure in milliseconds since epoch. Available on exit and historical visit types.  
confidence String The venue confidence, which is one of none, low, med, high  
locationType String The type of place the event corresponds to. One of venue, home, work, none, unknown  
otherPossibleVenues (Optional) Array<Venue> A list of other venues that the user might be at. Only returned if you have the checkbox selected in the Pilgrim console  

Venue

Key Type Description
id String The venue id
name String The venue name
location Location The location of the venue
categories Array<Category> The categories of the venue
probability Double Likelihood of this being the venue the device is actually at
hierarchy (optional) Array<Venue> The parent venues of this place, containing a subset of venue information (id, name, categories)
venueChains (optional) Array<Chain> The chains for which the venue belongs

Location

Key Type Description
address String The address of the venue
crossStreet String Venue cross street
city String The city of the venue
state String The state of the venue
postalCode String The postal code of the venue
country String The country of the venue
lat Double The latitude of the venue center
lng Double The longitude of the venue center

Category

Key Type Description
id String The category id
name String The category name
shortName String The shortened version of the category name i.e. American vs American Restaurant
pluralName String The plural name of the categories
icon Icon The category icon

Icon

Key Type Description
prefix String URL prefix
suffix String URL suffix

Chain

Key Type Description
id String The chain id

Examples

The following examples are also available for download.

{
   "pilgrimVisitId":"4c4763f7646e38002cc51789",
   "eventType":"placeArrival",
   "timestamp":1548182419000,
   "placeEvent":{
      "venues":[
         {
            "id":"52af211911d2aa9d4a1f0e0a",
            "name":"Foursquare Chicago",
            "location":{
               "address":"20 W Kinzie St",
               "crossStreet":"at N State St",
               "city":"Chicago",
               "state":"IL",
               "postalCode":"60606",
               "country":"US",
               "lat":41.889264,
               "lng":-87.628911
            },
            "categories":[
               {
                  "id":"4bf58dd8d48988d125941735",
                  "name":"Tech Startup",
                  "pluralName":"Tech Startups",
                  "shortName":"Tech Startup",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/shops/technology_",
                     "suffix":".png"
                  },
                  "primary":true
               }
            ],
            "hierarchy":[
               {
                  "id":"577d3752498e0faef85a21c2",
                  "name":"WeWork Kinzie",
                  "categories":[
                     {
                        "id":"4bf58dd8d48988d174941735",
                        "name":"Coworking Space",
                        "pluralName":"Coworking Spaces",
                        "shortName":"Coworking Space",
                        "icon":{
                           "prefix":"https://ss3.4sqi.net/img/categories_v2/building/office_coworkingspace_",
                           "suffix":".png"
                        },
                        "primary":true
                     }
                  ]
               }
            ],
            "venueChains":[
               {
                  "id":"556e5779bd6a82902e28bcea",
                  "name":"Foursquare"
               }
            ],
            "probability":0.33320653250353993
         }
      ],
      "otherPossibleVenues":[
         {
            "id":"577d3752498e0faef85a21c2",
            "name":"WeWork Kinzie",
            "location":{
               "address":"20 W Kinzie St",
               "crossStreet":"at N Dearborn St",
               "city":"Chicago",
               "state":"IL",
               "postalCode":"60654",
               "country":"US",
               "lat":41.889511244213416,
               "lng":-87.62894332408905
            },
            "categories":[
               {
                  "id":"4bf58dd8d48988d174941735",
                  "name":"Coworking Space",
                  "pluralName":"Coworking Spaces",
                  "shortName":"Coworking Space",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/building/office_coworkingspace_",
                     "suffix":".png"
                  },
                  "primary":true
               }
            ],
            "venueChains":[
               {
                  "id":"5569f639a7c8896abe7cb706",
                  "name":"WeWork"
               }
            ]
         },
         {
            "id":"5b0489c9b54618002cb921ee",
            "name":"Compass Regional HQ",
            "location":{
               "address":"20 W Kinzie St Fl 15",
               "crossStreet":"N State St",
               "city":"Chicago",
               "state":"IL",
               "postalCode":"60654",
               "country":"US",
               "lat":41.889252,
               "lng":-87.62892
            },
            "categories":[
               {
                  "id":"4bf58dd8d48988d124941735",
                  "name":"Office",
                  "pluralName":"Offices",
                  "shortName":"Office",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/building/default_",
                     "suffix":".png"
                  },
                  "primary":true
               },
               {
                  "id":"5032885091d4c4b30a586d66",
                  "name":"Real Estate Office",
                  "pluralName":"Real Estate Offices",
                  "shortName":"Real Estate",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/shops/realestate_",
                     "suffix":".png"
                  }
               }
            ],
            "hierarchy":[
               {
                  "id":"4bbf57a082a2ef3b7a972cd2",
                  "name":"20 W. Kinzie Building",
                  "categories":[
                     {
                        "id":"4bf58dd8d48988d130941735",
                        "name":"Building",
                        "pluralName":"Buildings",
                        "shortName":"Building",
                        "icon":{
                           "prefix":"https://ss3.4sqi.net/img/categories_v2/building/default_",
                           "suffix":".png"
                        },
                        "primary":true
                     }
                  ]
               }
            ],
            "probability":0.09861296257083949
         },
         {
            "id":"59518d9706fb6023d22a9ad7",
            "name":"Southern Cut Barbeque",
            "location":{
               "address":"20 W Kinzie St",
               "crossStreet":"",
               "city":"Chicago",
               "state":"IL",
               "postalCode":"60654",
               "country":"US",
               "lat":41.889384,
               "lng":-87.628605
            },
            "categories":[
               {
                  "id":"4bf58dd8d48988d1df931735",
                  "name":"BBQ Joint",
                  "pluralName":"BBQ Joints",
                  "shortName":"BBQ",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/food/bbqalt_",
                     "suffix":".png"
                  },
                  "primary":true
               }
            ],
            "probability":0.04432434057492494
         }
      ],
      "confidence":"high",
      "locationType":"venue",
      "arrivalTime":1548182419000
   },
   "lat":41.889303,
   "lng":-87.628898,
   "user":{
      "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
      "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
   },
   "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
   "sdkType":"iossdk",
   "segments":[
      {
         "segmentId":162,
         "name":"The Foursquare Coffee Drinker - U.S."
      }
   ]
}
{
   "pilgrimVisitId":"4c4763f7646e38002cc51789",
   "eventType":"placeDeparture",
   "timestamp":1548201189000,
   "placeEvent":{
      "venues":[
         {
            "id":"52af211911d2aa9d4a1f0e0a",
            "name":"Foursquare Chicago",
            "location":{
               "address":"20 W Kinzie St",
               "crossStreet":"at N State St",
               "city":"Chicago",
               "state":"IL",
               "postalCode":"60606",
               "country":"US",
               "lat":41.889264,
               "lng":-87.628911
            },
            "categories":[
               {
                  "id":"4bf58dd8d48988d125941735",
                  "name":"Tech Startup",
                  "pluralName":"Tech Startups",
                  "shortName":"Tech Startup",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/shops/technology_",
                     "suffix":".png"
                  },
                  "primary":true
               }
            ],
            "hierarchy":[
               {
                  "id":"577d3752498e0faef85a21c2",
                  "name":"WeWork Kinzie",
                  "categories":[
                     {
                        "id":"4bf58dd8d48988d174941735",
                        "name":"Coworking Space",
                        "pluralName":"Coworking Spaces",
                        "shortName":"Coworking Space",
                        "icon":{
                           "prefix":"https://ss3.4sqi.net/img/categories_v2/building/office_coworkingspace_",
                           "suffix":".png"
                        },
                        "primary":true
                     }
                  ]
               }
            ],
            "venueChains":[
               {
                  "id":"556e5779bd6a82902e28bcea",
                  "name":"Foursquare"
               }
            ]
         }
      ],
      "confidence":"high",
      "locationType":"venue",
      "arrivalTime":1548182419000,
      "departureTime":1548201189000
   },
   "lat":41.887604,
   "lng":-87.629599,
   "user":{
      "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
      "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
   },
   "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
   "sdkType":"iossdk",
   "segments":[
      {
         "segmentId":162,
         "name":"The Foursquare Coffee Drinker - U.S."
      }
   ]
}
{
   "pilgrimVisitId":"4c4b64fdd807ee002cba1560",
   "eventType":"placeArrival",
   "timestamp":1548444925000,
   "placeEvent":{
      "venues":[],
      "confidence":"high",
      "locationType":"work",
      "arrivalTime":1548444925000
   },
   "lat":41.889282,
   "lng":-87.62858,
   "user":{
      "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
      "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
   },
   "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
   "sdkType":"iossdk",
   "segments":[
      {
         "segmentId":162,
         "name":"The Foursquare Coffee Drinker - U.S."
      }
   ]
}
{
   "eventType":"geofenceEnter",
   "timestamp":1545078269223,
   "geofenceEvent":{
      "eventType":"entrance",
      "eventLat":41.8893897,
      "eventLng":-87.6297896,
      "radius":100.0,
      "venueId":"4a9037fef964a5209b1620e3",
      "categoryIds":"4bf58dd8d48988d1e0931735",
      "chainIds":"",
      "venues":[
         {
            "id":"4a9037fef964a5209b1620e3",
            "name":"Einstein Bros Bagels",
            "location":{
               "address":"400 N Dearborn St",
               "crossStreet":"",
               "city":"Chicago",
               "state":"IL",
               "postalCode":"60654",
               "country":"US",
               "lat":41.8893897,
               "lng":-87.6297896
            },
            "categories":[
               {
                  "id":"4bf58dd8d48988d179941735",
                  "name":"Bagel Shop",
                  "pluralName":"Bagel Shops",
                  "shortName":"Bagels",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/food/bagels_",
                     "suffix":".png"
                  }
               },
               {
                  "id":"4bf58dd8d48988d1e0931735",
                  "name":"Coffee Shop",
                  "pluralName":"Coffee Shops",
                  "shortName":"Coffee Shop",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
                     "suffix":".png"
                  }
               }
            ],
            "venueChains":[
               {
                  "id":"556ce8d9aceaff43eb0588d6",
                  "name":"Einstein Bros."
               }
            ]
         }
      ]
   },
   "lat":41.88928251303856,
   "lng":-87.62870316744883,
   "user":{
      "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
      "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
   },
   "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
   "sdkType":"iossdk"
}
{
   "eventType":"geofenceDwell",
   "timestamp":1545078408140,
   "geofenceEvent":{
      "eventType":"dwell",
      "eventLat":41.8893897,
      "eventLng":-87.6297896,
      "radius":100.0,
      "venueId":"4a9037fef964a5209b1620e3",
      "categoryIds":"4bf58dd8d48988d1e0931735",
      "chainIds":"",
      "venues":[
         {
            "id":"4a9037fef964a5209b1620e3",
            "name":"Einstein Bros Bagels",
            "location":{
               "address":"400 N Dearborn St",
               "crossStreet":"",
               "city":"Chicago",
               "state":"IL",
               "postalCode":"60654",
               "country":"US",
               "lat":41.8893897,
               "lng":-87.6297896
            },
            "categories":[
               {
                  "id":"4bf58dd8d48988d179941735",
                  "name":"Bagel Shop",
                  "pluralName":"Bagel Shops",
                  "shortName":"Bagels",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/food/bagels_",
                     "suffix":".png"
                  }
               },
               {
                  "id":"4bf58dd8d48988d1e0931735",
                  "name":"Coffee Shop",
                  "pluralName":"Coffee Shops",
                  "shortName":"Coffee Shop",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
                     "suffix":".png"
                  }
               }
            ],
            "venueChains":[
               {
                  "id":"556ce8d9aceaff43eb0588d6",
                  "name":"Einstein Bros."
               }
            ]
         }
      ]
   },
   "lat":41.889335266663636,
   "lng":-87.62856037188838,
   "user":{
      "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
      "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
   },
   "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
   "sdkType":"iossdk"
}
{
   "eventType":"geofenceExit",
   "timestamp":1545091987992,
   "geofenceEvent":{
      "eventType":"exit",
      "eventLat":41.8893897,
      "eventLng":-87.6297896,
      "radius":100.0,
      "venueId":"4a9037fef964a5209b1620e3",
      "categoryIds":"4bf58dd8d48988d1e0931735",
      "chainIds":"",
      "venues":[
         {
            "id":"4a9037fef964a5209b1620e3",
            "name":"Einstein Bros Bagels",
            "location":{
               "address":"400 N Dearborn St",
               "crossStreet":"",
               "city":"Chicago",
               "state":"IL",
               "postalCode":"60654",
               "country":"US",
               "lat":41.8893897,
               "lng":-87.6297896
            },
            "categories":[
               {
                  "id":"4bf58dd8d48988d179941735",
                  "name":"Bagel Shop",
                  "pluralName":"Bagel Shops",
                  "shortName":"Bagels",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/food/bagels_",
                     "suffix":".png"
                  }
               },
               {
                  "id":"4bf58dd8d48988d1e0931735",
                  "name":"Coffee Shop",
                  "pluralName":"Coffee Shops",
                  "shortName":"Coffee Shop",
                  "icon":{
                     "prefix":"https://ss3.4sqi.net/img/categories_v2/food/coffeeshop_",
                     "suffix":".png"
                  }
               }
            ],
            "venueChains":[
               {
                  "id":"556ce8d9aceaff43eb0588d6",
                  "name":"Einstein Bros."
               }
            ]
         }
      ]
   },
   "lat":41.88709567122635,
   "lng":-87.63105850113463,
   "user":{
      "adid":"40C23EBD-E21A-4ACC-A915-B1C80BDAF4FE",
      "userId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4"
   },
   "installId":"CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4",
   "sdkType":"iossdk"
}


Next Steps

The true power of Pilgrim begins to showcase itself once you start integrating its event detection with other services. Pilgrim supports a number of third-party integration options.

Third-Party Integrations