Webhooks are used as a signal between applications. You can see it as a callback from a different context. This call is made with the HTTP protocol (possibly with SSL). An attempt is made to provide information as efficiently as possible and in real time, and JSON is usually used as a data format.
The strength lies in the fact that as few operations as possible are necessary in order to get feedback. Usually, the most work lies in the implementation of the signal.
For a proof of concept, consider the following. Let's assume that when we push new code to GitLab, we have to send a signal from GitLab to an application that we have built ourselves.
To implement this model, we've chose the lightweight Flask micro-framework for Python:
from flask import Flask, request
import json
app = Flask(__name__)
def runsomething():
print "This is triggered"
@app.route('/',methods=['POST'])
def trigger():
data = json.loads(request.data)
print "New commit by: {}".format(data['commits'][0]['author']['name'])
print "New commit by: {}".format(data['commits'][0]['author']['email'])
print "New commit by: {}".format(data['commits'][0]['message'])
runsomething()
return "OK"
if __name__ == '__main__':
app.run()
Let's run through this code step by step. In the following code, the basic app has been initiated. The imports are purely the basic Flask framework and, in particular, the request object. The app is instantiated:
from flask import Flask, request
import json
app = Flask(__name__)
The following function can be used to do the real work:
def runsomething():
print "This is triggered"
Then follows the method that is decorated with a route, and parses the request for certain information. There's no check here – just reading the information from the JSON webhook, running the real work function, and returning OK:
@app.route('/',methods=['POST'])
def trigger():
data = json.loads(request.data)
print "New commit by: {}".format(data['commits'][0]['author']['name'])
print "New commit by: {}".format(data['commits'][0]['author']['email'])
print "New commit by: {}".format(data['commits'][0]['message'])
runsomething()
return "OK"
The following main part, combined with the first block, is part of the basic Flask implementation:
if __name__ == '__main__':
app.run()
When you run this code with python server.py, it will open port 5000 on the localhost:
Joosts-iMac:gitlab-webhook joostevertse$ python server.py
* Running on http://127.0.0.1:5000/
If we want something on the internet to connect to it, we can use the venerable ngrok to link the port:
Joosts-iMac:Downloads joostevertse$ ngrok http 5000
ngrok is now running, as shown in the following screenshot:
We can now define the webhook in GitLab. You can find it in the Settings | Integrations section of your GitLab project. After you have defined the hook, you can run a test to verify its operation:
We get the following result when a call is triggered through GitLab. This is the connection going through the ngrok proxy:
In GitLab, if you click the Edit button, you will see the result of the webhook call. It will contain the body that was sent:
You will also see the response that was given by the other end. You can see the OK response clearly:
The result of this call was that our custom method was triggered and some specific information such as author, email, and message was printed on stdout:
Joosts-iMac:gitlab-webhook joostevertse$ python server.py
* Running on http://127.0.0.1:5000/
New commit by: Joost
New commit by: [email protected]
New commit by: Added text
This is triggered
127.0.0.1 - - [03/Mar/2019 17:10:39] "POST / HTTP/1.1" 200 -
We have seen that it is also possible to use a generic event mechanism such as webhooks. You can modify your own software or commercial-off-the-shelf (COTS) application to receive events from GitLab.