Installing and Configuring a Webhook

Introduction

This tutorial explains how to install and configure webhook by adnanh to trigger a shell script. Webhook by adnanh is a service written in Go that exposes a lightweight web server. When you call a specific route on the web server, you can run a command or shell script on your server. In the shell script, you can start a deployment or some other actions.

Requirements

You need the package manager APT. You also need a text editor, for example vi or nano, to create and change config files.

Step 1 - Updating your packages and installing webhook by adnanh

Run these commands:

sudo apt-get update && sudo apt-get -y upgrade
sudo apt-get install webhook

Then check the version:

webhook -version

Step 2 - Create the webhook configuration file

Create the webhook configuration file with a text editor of your choice:

vi /etc/webhook.conf

Paste the webhook configuration:

[
   {
      "id": "deploy-webhook",
      "execute-command": "/var/app/webhook-entrypoint.sh",
      "command-working-directory": "/var/app",
      "include-command-output-in-response": true,
      "include-command-output-in-response-on-error": true,
   }
]

Save the configuration file.

We defined only one webhook in an array in the JSON config file. Here we use the execute-command property to define the shell script path. The base path is defined in the command-working directory. Later in this tutorial, we will execute our webhook with an HTTP request. With the include-command-output-in-response property, the webhook will include the stdoutput of the shell script in the HTTP response body. With the include-command-output-in-response-on-error property, the webhook includes the erroutput of the shell script in the HTTP response body. The HTTP request waits until all the output is collected. If the exit code of the shell script is zero, the status code of an HTTP request is 200. If the exit code is not zero, the status code is not 200. You have the option to remove the two "include-*" properties, then you will not see the output of the shell script in the HTTP response body. For security reasons, it is recommended not to include the output in the HTTP response code.

Step 3 - Create the app directory

Create the app directory:

mkdir -p /var/app

Step 4 - Create the webhook-entrypoint.sh file and make it executable

Create a new file with a text editor of your choice:

vi /var/app/webhook-entrypoint.sh

Insert the following:

##!/bin/bash

echo 'Execute webhook-entrypoint.sh-script. Here you can do for example a deployment.'

Save the file.

Make the file executable:

chmod +x /var/app/webhook-entrypoint.sh

Step 5 - Restart webhook service to activate all changes

IMPORTANT: If you make changes to your webhook configuration, you must restart the webhook service to activate all changes. To activate the configuration run the command:

service webhook restart

Step 6 - Test your webhook with a curl command

From the same server, you can test your webhook with the hostname "localhost":

curl http://localhost:9000/hooks/deploy-webhook

From a different server or your local computer, you can test your webhook with your server IP address:

curl http://<server-ip-address>:9000/hooks/deploy-webhook

The response of the HTTP request should look like:

Execute webhook-entrypoint.sh-script. Here you can do for example a deployment.

Conclusion

You learned how to install and configure webhook by adnanh. With the webhook you can start a deployment on your server with a simple curl command from a different server or PC.

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.s

Contributor's Certificate of Origin

By making a contribution to this project, I certify that:

1. The contribution was created in whole or in part by me and I have the right to submit it under the license indicated in the file; or

2. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same license (unless I am permitted to submit under a different license), as indicated in the file; or

3. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

4. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the license(s) involved.