In the standard integration of the Pilgrim SDK, the SDK will call your app with a notification that your user 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 a specified URL called anytime one of your user arrives at a place.
To learn more about the benefits of using a webhook or learn more about what the webhook payload looks like, head over to our documentation site: https://developer.foursquare.com/docs/pilgrim-sdk/integrations#webhooks
What is ngrok?
When you’re developing your application in your local development environment, your app is only reachable by other programs on the same computer, so Pilgrim won’t naturally be able to talk to it.
Ngrok is our favorite tool for solving this problem. Once started, it provides a unique URL on the ngrok.io domain which will forward incoming requests to your local development environment. This is referred to as a tunnel.
You can also use ngrok all by itself (without even needing to build a server side application) as a way to confirm and monitor webhook activity as it comes in.
To start, go to ngrok.com and create a free ngrok account:
- Download ngrok for your local machine.
- Unzip the install (for Mac OSX, we suggest putting ngrok in your user directory)
- Connect your account. From a terminal window:
./ngrok authtoken *api_key*(note, this might be slightly different for you, depending on where you installed ngrok to.)
- (Optional) If you have an application you want to use to accept the webhook payloads, make sure your server is running locally.
- From terminal:
./ngrok http 9292(where 9292 is the local port to listen to) a. If you don’t have a local application running, any port number will most likely do. b. If you do have a local application running, you’ll want to change this port to match the port your application is running on.
- Once you have successfully started ngrok, you will be given a
https://*.ngrok.ioforwarding web address that you can use to access your local server.
Visit your ngrok dashboard
You can now visit
http://localhost:4040 in your browser to see a dashboard that contains live requests coming through your ngrok tunnel.
Initially, this page will be empty:
But once you start making requests to the supplied ngrok.io forwarding URL (in the above example:
http://43903967.ngrok.io), you’ll start to see results that look like this:
(Note: In the above example, we aren’t running an application, so server returns a 502 error. This is expected and just the system letting us know it couldn’t find a local application to talk to.)
Update your Pilgrim Configuration settings
You are now ready to accept Pilgrim webhook payloads! You’ll want to head over to your Pilgrim Confirmation page, which is accessible from your Foursquare Developers dashboard. The Pilgrim Configuration page will look something like:
Where CLIENT_ID is the CLIENT_ID from your Pilgrim app. If you don’t have Pilgrim access yet, follow these steps: https://developer.foursquare.com/docs/pilgrim-sdk/overview#pilgrim-sdk-access
Next, you’ll want to scroll down to the Webhook section and add the https version of your ngrok.io url to your Pilgrim Configuration Webhook URL:
Once you’ve updated your webhook’s URL with your ngrok.io forwarding URL, don’t forget to click save.
You’ll also notice that there is a “Send test push” button. Upon clicking this, Pilgrim will send a sample visit to your webhook URL. If you look at your ngrok dashboard (
http://localhost:4040), you’ll now see a POST call from Foursquare with the following test webhook payload:
And that’s it! You’ve just gotten a successful webhook payload from Pilgrim! Now, as you begin testing your iOS and/or Android app, as long as your ngrok tunnel is running, you’ll be able to track the Pilgrim activity via webhook.