Run web hook(s) in development

Webhooks provide a type of "reverse" API, in that the SHF app presents a end point, to an external client or service, that can be invoked via HTTP (and usually as a POST action). There's lot of information out there on this topic.

For a development environment, webhooks present a problem in that the end point (in our app) has to be accessible via HTTP over the internet. To solve this problem, you can use ngrok. This sets up a proxy on your machine that bridges your localhost to an external service, which in turn receives the webhook calls and forwards then to localhost.

Read about and get the tool here. This article by lullabot also contains a good discussion as to how to set up ngrok.

Some things to keep in mind if you're using the free version of ngrok:

• you need to ensure ngrok is running each time you restart your system (and are planning on using webhooks in development)
• ngrok will assign you a random web address each time it starts so you'll need to update SHF_DEV_WEBHOOK_HOST and the whitelisted IP each time (steps 3 & 4 below)

Running ngrok with SHF:

1. Run ngrok from the command line (terminal):

ngrok http <port-your-rails-app-uses>

• If you're running on the default Rails port 3000 you'll see something like

  Rails 5.1.0 application starting in development on http://0.0.0.0:3000

  when you start the application. The port number is the number that comes at the end of that line, after the :

  And you can start ngrok like this:

      ngrok http 3000

2. Once ngrok starts, you'll see something like this is your terminal window:

3. Add ENV variables to .env.development

Create the file .env.development in the app home directory (if it doesn't already exist), and add this line to that file:

SHF_DEV_WEBHOOK_HOST = '<ngrok-host-url>'

Where the host url is the forwarding url shown in the terminal window. For example:

SHF_DEV_WEBHOOK_HOST = 'http://a7c25d48.ngrok.io'

4. You may need to whitelist ngrok

You may need to 'whitelist' the ngrok IP address so that your rails server will allow the connection from that remote (IP) address. To do so, add the following line to your config/environments/development.rb file:

config.web_console.whitelisted_ips = '207.159.142.100'

Replace '207.159.142.100' with the IP address that ngrok uses to connect to your local machine.

You can see the address in your rails logs if you've already tried an action that calls a webhook,

or: Make a visit to the app from the ngrok web interface page. ngrok will then establish a connection and you'll see the IP address that it uses on the web interface:

1. Make sure you have the SHF Rails app running.
2. Go to the the "Web interface" page that ngrok shows in the terminal. This is the local webpage that displays your ngrok status. It's usually http://localhost:4040. It will look something like this:

3. Click on one of the tunnel URL links. Doing so will take you through the tunnel that ngrok has set up to the SHF app running on your local machine. Ex: I click on the "http://be46399a.ngrok.io" link above, and that takes me to some ngrok server, which then assign a random IP address that ngrok map to my local machine. So: http://be46399a.ngrok.io -> ngrok server -> random IP address assigned -> my local machine.

4. Once you have visited your site, go back to the ngrok Web Interface page. You should now see that ngrok has sent through a GET request to you. You can now see the IP address that ngrok used. That is the IP address to whitelist.

Don't forget that each time you restart ngrok it will assign a new random address to you and you'll need to update the the IP address to whitelist and SHF_DEV_WEBHOOK_HOST.