Webhooks are a way for a web application to provide data to other web applications in real-time. As a practical example, consider having a GitHub repository with many contributors. There also exists a continuous integration (e.g Travis CI) setup that runs tests and ensures changes to the master branch do not break anything. How does Travis know that a change has been made to the repository? One way is to query the GitHub API every 5 seconds to check for changes. An obvious problem comes up with calls being redundant and that is where webhooks come in. When a specified condition is set, GitHub sends a post request to your app detailing the change.
(More on webhooks can be found here.)

When doing development work on localhost, you need a way of testing webhooks. The post request has to be made to an actual unique address and unfortunately, cannot be used in this case. To work around this, we use ngrok. It receives the post payload on our behalf and tunnels it to our localhost. More information on how this works can be found on their website.

Below, we demonstrate how to set this up.

Step 1: Download and Install ngrok 
Head over to https://ngrok.com/download and download the version compatible with your platform. Unzip the file to get the executable file. Running this file will create a command prompt window but more on that later.

Download page for ngrok
Executable after unzipping downloaded folder (For windows)

Step 2: Creating a small application to simulate receiving the webhook post request 
Below is code for a simple flask app with a single route to receive the data from the webhook. The route parses the JSON from the POST request and prints it to the terminal. The route must return a response with code 2XX to notify the other app of success.

from flask import Flask, request

app = Flask(__name__)

@app.route('/get-notification', methods=['POST'])
def handle_webhook():
    #get json
    data = request.get_json()
    print("Data received from the webhook is: ", data)

    return "OK"

if __name__ == "__main__":

Step 3: Run ngrok and simulate the webhook using Postman 
Launching the ngrok file pops up a command window. Typing command:
ngrock http localhost:5000 launches another window showing more details. The port number can be changed to any that your app is running on.

Public-facing addresses being forwarded to your localhost. NOTE: It is best not to share the forwarding details publicly unless for demonstration purposes only.

Now we open up postman and send a POST request to the public address http://ea0a582b.ngrok.io/get-notifications The flask app should also be running at this time.

Post request via postman

The request is successful and the flask app route received the JSON payload.

JSON sent by Postman printed to console

For more information on advanced functionality and more features, visit

Categories: FlaskPython

Leave a Reply

Your email address will not be published. Required fields are marked *