Webhooks - V1

This page contains the structure for version 1 of the Pilgrim webhook, which is deprecated. It is highly encouraged that you update to the latest version.

Payload

The notification will come to your server endpoint as a x-www-urlencoded POST request. You can download example webhook notification JSON from Dropbox here.

Params

Param Value
json The content of the notification in a JSON serialized string
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.
arbitrary params 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” alongside JSON. The arbitrary params should be set before starting the SDK.

JSON

The content represented in the JSON string from the top level parameter.

Key Type Description
venues Array<Venue> The place the user is at. Currently, a max of 1 item is sent.
confidence String The venue confidence, which is one of none, low, med, or high
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
pilgrimVisitId String The unique ID of the visit. Required for confirming visits back to Foursquare
timestamp long Time of the event in milliseconds since epoch
visitType String The type of notification that is coming through: arrival, departure, historical.
locationType String The type of place the event corresponds to. One of venue, home, work, none, or unknown
sdkType String The SDK that generated the notification iosSdk or androidSdk
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.
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
nearbyVenues (Optional) Array<Venue> The list of places nearby that matched your selected nearby triggers as configured on the Pilgrim console or locally in the SDK on a per user basis.

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
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
crossStreet String Venue cross street
address String The address of the venue
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

Example webhook payload

{
  "secret": "XXXXXX",
  "json": {
    "venues": [
      {
        "id": "412d2800f964a520df0c1fe3",
        "name": "Central Park",
        "location": {
          "address": "59th St to 110th St",
          "crossStreet": "5th Ave to Central Park West",
          "city": "New York",
          "state": "NY",
          "postalCode": "10028",
          "country": "US",
          "lat": 40.788859944495,
          "lng": -73.961162567139
        },
        "categories": [
          {
            "id": "4bf58dd8d48988d163941735",
            "name": "Park",
            "pluralName": "Parks",
            "shortName": "Park",
            "icon": {
              "prefix": "https://ss3.4sqi.net/img/categories_v2/parks_outdoors/park_",
              "suffix": ".png"
            }
          }
        ],
        "venueChains": []
      }
    ],
    "confidence": "med",
    "locationType": "venue",
    "pilgrimVisitId": "593eede7d48ec143c034a349",
    "visitType": "arrival",
    "timestamp": 1497296359056,
    "lat": 40.777502,
    "lng": -73.969508,
    "sdkType": "androidsdk"
  }
}

Next Steps: Migrate to v2

Being that version 1 of the Pilgrim webhook is deprecated, it is highly encouraged that you update to the latest version. You can update to use v2 from your Foursquare Developer app's Pilgrim console:

pilgrim webhooks version

Version Mapping

The following is a mapping of fields as they are structured in v1 and v2 of the webhook:

V1 V2
secret Will be provided in headers, not json body.
json/pilgrimVisitId pilgrimVisitId
json/locationType placeEvent/locationType
json/visitType (arrival, departure, historical) eventType (placeArrival, placeDeparture, or placeHistorical)
json/confidence placeEvent/confidence
json/lat lat
json/lng lng
json/sdkType sdkType
json/timestamp timestamp
json/arrivalTime placeEvent/arrivalTime
json/departureTime placeEvent/departureTime
json/venues placeEvent/venues
json/otherPossibleVenues placeEvent/otherPossibleVenues
json/nearbyVenues No longer available. Encouraged to use geofencing.
arbitrary params (custom defined user fields) -- these show up on the body as whatever field name was set. For example: `setUserInfo("my custom value", forKey: "myCustomField")` would show up as `myCustomField` at the same level as json user/myCustomField
N/A (not available in v1) segments
N/A (requires you adding as a custom defined user field) installId

Side by Side Comparison

V1 V2

{% capture v1include %} { "secret": "XXXXXX", "json": { "venues": [ { "id": "3fd66200f964a52098ed1ee3", "name": "The Irish Bank", "location": { "address": "10 Mark Ln", "crossStreet": "at Harlan Pl.", "city": "San Francisco", "state": "CA", "postalCode": "94108", "country": "US", "lat": 37.7903451920591, "lng": -122.40459322929382 }, "categories": [ { "id": "52e81612bcbc57f1066b7a06", "name": "Irish Pub", "pluralName": "Irish Pubs", "shortName": "Irish", "icon": { "prefix": "https://ss3.4sqi.net/img/categoriesv2/nightlife/pub", "suffix": ".png" } } ], "probability": 0.6088516762188961 } ], "otherPossibleVenues": [ { "id": "49e7e380f964a52027651fe3", "name": "Akiko’s Restaurant & Sushi Bar", "location": { "address": "431 Bush St", "crossStreet": "at Mark Ln.", "city": "San Francisco", "state": "CA", "postalCode": "94108", "country": "US", "lat": 37.790623, "lng": -122.404657 }, "categories": [ { "id": "4bf58dd8d48988d1d2941735", "name": "Sushi Restaurant", "pluralName": "Sushi Restaurants", "shortName": "Sushi", "icon": { "prefix": "https://ss3.4sqi.net/img/categoriesv2/food/sushi", "suffix": ".png" } }, { "id": "4bf58dd8d48988d111941735", "name": "Japanese Restaurant", "pluralName": "Japanese Restaurants", "shortName": "Japanese", "icon": { "prefix": "https://ss3.4sqi.net/img/categoriesv2/food/japanese", "suffix": ".png" } } ], "probability": 0.042400647818909835 }, { "id": "4ed92126f5b92139871ce962", "name": "Foursquare SF", "location": { "address": "425 Bush St Ste 500", "crossStreet": "btwn Grant & Kearny", "city": "San Francisco", "state": "CA", "postalCode": "94108", "country": "US", "lat": 37.7905997608588, "lng": -122.40459154855427 }, "categories": [ { "id": "4bf58dd8d48988d125941735", "name": "Tech Startup", "pluralName": "Tech Startups", "shortName": "Tech Startup", "icon": { "prefix": "https://ss3.4sqi.net/img/categoriesv2/shops/technology", "suffix": ".png" } } ], "venueChains": [ { "id": "556e5779bd6a82902e28bcea", "name": "Foursquare" } ], "probability": 0.01599619603673202 }, ... ], "confidence": "med", "locationType": "venue", "pilgrimVisitId": "593eede7d48ec143c034a349", "visitType": "arrival", "timestamp": 1497296359056, "lat": 40.777502, "lng": -73.969508, "sdkType": "androidsdk", "arrivalTime": 1497296359056 }, "userId": "jIkQZBHGrDJt6gMeXlcrWBRO8fStdETO", "myCustomField": "my custom value" } {% endcapture %} {% highlight json %} {{ v1include }} {% endhighlight %}

    </td>
    <td>

{% capture v2include %} { "pilgrimVisitId": "5b8821d9bcbf7a002dab91fc", "eventType": "placeArrival", "timestamp": 1535648217088, "placeEvent": { "venues": [ { "id": "3fd66200f964a52098ed1ee3", "name": "The Irish Bank", "location": { "address": "10 Mark Ln", "crossStreet": "at Harlan Pl.", "city": "San Francisco", "state": "CA", "postalCode": "94108", "country": "US", "lat": 37.7903451920591, "lng": -122.40459322929382 }, "categories": [ { "id": "52e81612bcbc57f1066b7a06", "name": "Irish Pub", "pluralName": "Irish Pubs", "shortName": "Irish", "icon": { "prefix": "https://ss3.4sqi.net/img/categoriesv2/nightlife/pub", "suffix": ".png" } } ], "probability": 0.6088516762188961 } ], "otherPossibleVenues": [ { "id": "49e7e380f964a52027651fe3", "name": "Akiko’s Restaurant & Sushi Bar", "location": { "address": "431 Bush St", "crossStreet": "at Mark Ln.", "city": "San Francisco", "state": "CA", "postalCode": "94108", "country": "US", "lat": 37.790623, "lng": -122.404657 }, "categories": [ { "id": "4bf58dd8d48988d1d2941735", "name": "Sushi Restaurant", "pluralName": "Sushi Restaurants", "shortName": "Sushi", "icon": { "prefix": "https://ss3.4sqi.net/img/categoriesv2/food/sushi", "suffix": ".png" } }, { "id": "4bf58dd8d48988d111941735", "name": "Japanese Restaurant", "pluralName": "Japanese Restaurants", "shortName": "Japanese", "icon": { "prefix": "https://ss3.4sqi.net/img/categoriesv2/food/japanese", "suffix": ".png" } } ], "probability": 0.042400647818909835 }, { "id": "4ed92126f5b92139871ce962", "name": "Foursquare SF", "location": { "address": "425 Bush St Ste 500", "crossStreet": "btwn Grant & Kearny", "city": "San Francisco", "state": "CA", "postalCode": "94108", "country": "US", "lat": 37.7905997608588, "lng": -122.40459154855427 }, "categories": [ { "id": "4bf58dd8d48988d125941735", "name": "Tech Startup", "pluralName": "Tech Startups", "shortName": "Tech Startup", "icon": { "prefix": "https://ss3.4sqi.net/img/categoriesv2/shops/technology", "suffix": ".png" } } ], "venueChains": [ { "id": "556e5779bd6a82902e28bcea", "name": "Foursquare" } ], "probability": 0.01599619603673202 }, ... ], "confidence": "high", "locationType": "venue" }, "lat": 37.790459, "lng": -122.404695, "user": { "userId": "jIkQZBHGrDJt6gMeXlcrWBRO8fStdETO", "myCustomField": "my custom value" }, "installId": "CB25EFFB-C2B2-4E0F-B0E9-55C05BEFA4D4", "sdkType": "iossdk", "segments": [{ "segmentId": "162", "name": "The Foursquare Coffee Drinker - U.S." }] } {% endcapture %} {% highlight json %} {{ v2include }} {% endhighlight %}

    </td>
  </tr>
</tbody>
Back to V2 Documentation