Ever wanted to run an arbitrary script from anywhere with flexible authentication? Let me introduce Webhook!

I’ll show you how I set up my blog to automatically render and deploy every time I push to master on a Gitea instance.

Install

Install Webhook on the machine on which you want an automated action to occur.

Go download the Webhook binary, or build it yourself.

$ go get github.com/adnanh/webhook

Configuration

Create hooks.json and a folder to contain everything.

$ mkdir webhook && cd webhook
$ touch hooks.json

Inside hooks.json, copy this template, and update the location of the script you wish to execute.

[
  {
    "id": "redeploy-blog",
    "execute-command": "/home/arran/hugo_websites/redeploy.sh",
    "command-working-directory": "/home/arran/",
  }
]

For the curious, here’s what is inside my redeploy.sh.

#!/bin/env bash

REPO="${HOME}/hugo_websites/by.arran.nz/"

git -C ${REPO} fetch && git -C ${REPO} rebase
git -C ${REPO} submodule update --remote --rebase  
HUGO_CACHEDIR=${HOME}/tmp hugo --cleanDestinationDir --destination /var/www/virtual/${USER}/html --source ${REPO}

Running

I’m hosting my blog on Uberspace, and Uberspace uses Supervisor to manage services.

If you’re not using Uberspace, run Webhook in any way you can on your machine.

webhook -hooks hooks.json -logfile out.log -hotreload

Supervisor

To create a new service, make a file located at ~/etc/services.d/webook.ini.

[program:webhook]
directory=%(ENV_HOME)s/webhook
autostart=true
autorestart=true
startretries=3
command=/home/arran/go/bin/webhook -hooks hooks.json -logfile out.log -hotreload

After creating the configuration, tell supervisord to refresh its configuration and start the service:

$ superviserctl reread
$ superviserctl update
$ supervisorctl status
webhook                          RUNNING   pid 13102, uptime 0:35:37

Check out the Uberspace supervisord manual for further details.

Uberspace Backend

If you’re using Uberspace, configure the Uberspace backend to point port 80 to Webhook running under port 9000 - This is the default.

$ uberspace web backend set arran.uber.space --http --port 9000
Set backend for arran.uber.space/ to port 9000; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".

For more information, check out the Uberspace Manual

Sanity Check

Now that a service is running and is exposed to the internet, test it.

Considering the webhook is named redeploy-blog, send a POST to:

$ curl -X POST https://arran.uber.space/hooks/redeploy-blog

Confirm the webhook was successful by checking the logs located at ~/webhook/out.log as defined in webhook.ini.

$ cat out.log
...
[webhook] 2020/11/17 13:24:05 [7f6850] redeploy-blog got matched
[webhook] 2020/11/17 13:24:05 [7f6850] redeploy-blog hook triggered successfully
...

Secure the Webhook 🔐

Note: Make sure to setup Webhook with https before implementing this step - Don’t go sending your secrets over http!

You may have noticed anyone can call this Webhook - Let’s fix that.

My blog’s git repository is currently hosted at Codeberg, which is a Gitea instance. Configure Webhook to read the secret from a Gitea instance.

Add a trigger-rule to the hooks.json we created earlier - Replace the secret with your own.

[
  {
    "id": "redeploy-blog",
    "execute-command": "/home/arran/hugo_websites/redeploy.sh",
    "command-working-directory": "/home/arran/",
    "trigger-rule":
    {
      "and":
      [
        {
          "match":
          {
            "type": "value",
            "value": "____GITEA_SECRET____",
            "parameter":
            {
              "source": "payload",
              "name": "secret"
            }
          }
        },
        {
          "match":
          {
            "type": "value",
            "value": "refs/heads/master",
            "parameter":
            {
              "source": "payload",
              "name": "ref"
            }
          }
        }
      ]
    }
  }
]

Now Webhook will only allow execution when the request matches the trigger-rule.

For further examples, reference the Hook Examples.

Setting up Gitea

Head on over to your Gitea instance’s repo Repo > Settings > Webhooks, punch in the URL and secret, and you’re good to go!

Relax

Now, every time you push to master on a Gitea repository, the Webhook will be called - One more thing automated.

I hope you can generalize this information and add Webhook to your toolbox when you need to automate something simple in the future.

No affiliation with Uberspace or Codeberg - But I can recommend them!

Automate Simply With Webhook