webhookd

In the Azure Portal, search the Marketplace for webhookd, select the SecureAnyCloud publisher, and click Create. Configure the NSG to allow TCP 443 (HTTPS API) from the networks that will call your webhooks, and TCP 22 for administration.

Keep port 443 restricted to trusted networks. webhookd runs shell scripts, so treat the endpoint as privileged.

Accept the Marketplace terms, create the VM, then open ports 443 and 22 on its NSG.

RG="webhookd-prod"; LOCATION="eastus"; VM_NAME="webhookd1" IMAGE_URN="sac1647283583153:webhookd-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION"
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:webhookd-ubuntu-24-04:default:latest
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$IMAGE_URN" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
# Open the API and admin ports on the VM's NSG (restrict 443 to your caller networks):
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 443 --priority 1001
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1002

On first boot, the image resolves the VM address and generates a per-VM nginx TLS certificate. It also generates a unique per-VM Basic auth password and writes it to the htpasswd file. Then it starts webhookd and nginx, and proves that an unauthenticated request is refused while an authenticated request runs the example hook. This completes within a minute.

SSH in as azureuser and read the credentials.

sudo cat /root/webhookd-credentials.txt

Expected output. The password is unique to your VM.

webhookd.user=sac webhookd.pass=<per-VM-password> webhookd.host=10.0.0.5 webhookd.url=https://10.0.0.5/ webhookd.example_hook=https://10.0.0.5/echo webhookd.htpasswd=/etc/webhookd/htpasswd webhookd.scripts_dir=/opt/webhookd/scripts

webhookd.service is active and owns the loopback port 8080, and nginx.service terminates TLS on port 443. webhookd is deliberately not exposed directly, and all external traffic goes through the nginx TLS endpoint.

systemctl is-active webhookd.service
systemctl is-active nginx.service
sudo ss -tlnp | grep -E '127.0.0.1:8080 |:443 '

Expected output:

active active LISTEN 0 4096 127.0.0.1:8080 0.0.0.0:* users:(("webhookd",pid=2075,fd=3)) LISTEN 0 511 0.0.0.0:443 0.0.0.0:* users:(("nginx",pid=2101,fd=6))

The example hook lives at /opt/webhookd/scripts/echo.sh and is reachable at https://<host>/echo. A request without credentials is refused with HTTP 401. A request with the per-VM credentials runs the hook and returns its output with HTTP 200.

The certificate is self-signed, so use curl -k or trust the per-VM certificate. The commands below read the username and password from the credentials file.

WU="$(sudo grep -E '^webhookd\.user=' /root/webhookd-credentials.txt | cut -d= -f2-)" WP="$(sudo grep -E '^webhookd\.pass=' /root/webhookd-credentials.txt | cut -d= -f2-)" curl -k -s -o /dev/null -w 'unauthenticated request: HTTP %{http_code}\n' https://127.0.0.1/echo curl -k -s -u "$WU:$WP" https://127.0.0.1/echo
sudo /usr/local/sbin/webhookd-roundtrip.sh

Expected output:

unauthenticated request: HTTP 401 sac webhookd example hook hook_name=echo method=GET authenticated_user= step 1/3 working... step 2/3 working... step 3/3 working... done: hook completed successfully round-trip OK: hook 'echo' — no credentials refused (HTTP 401), wrong credentials refused (HTTP 401), correct per-VM credentials ran the hook and returned its output (HTTP 200); enforced on both the loopback backend (:8080) and the nginx TLS edge (:443)

webhookd streams a hook's output to the caller as the script runs, rather than buffering until it finishes. Send Accept: text/event-stream to receive Server-Sent Events, or use the default chunked mode. Because nginx runs with response buffering disabled, the lines arrive in real time as the example hook emits them.

WU="$(sudo grep -E '^webhookd\.user=' /root/webhookd-credentials.txt | cut -d= -f2-)" WP="$(sudo grep -E '^webhookd\.pass=' /root/webhookd-credentials.txt | cut -d= -f2-)" curl -k -N -u "$WU:$WP" -H 'Accept: text/event-stream' https://127.0.0.1/echo

Expected output. Each data: line arrives as the script prints it.

data: sac webhookd example hook data: hook_name=echo method=GET authenticated_user= data: step 1/3 working... data: step 2/3 working... data: step 3/3 working... data: done: hook completed successfully

webhookd is configured from /etc/webhookd/webhookd.env. It binds the loopback interface only, points at the scripts directory, and enforces Basic auth through the htpasswd file. The htpasswd file holds this VM's unique password as a bcrypt hash, never as plaintext and never baked into the image.

/usr/local/bin/webhookd -version | head -1 grep -vE '^[[:space:]]*#|^[[:space:]]*$' /etc/webhookd/webhookd.env
sudo sed -E 's/(:\$2[aby]\$).*/\1<bcrypt-hash-masked>/' /etc/webhookd/htpasswd | grep -vE '^[[:space:]]*#'

Expected output, with the bcrypt hash masked.

Version: v1.22.0 WHD_LISTEN_ADDR=127.0.0.1:8080 WHD_HOOK_SCRIPTS=/opt/webhookd/scripts WHD_PASSWD_FILE=/etc/webhookd/htpasswd WHD_HOOK_TIMEOUT=30 WHD_HOOK_DEFAULT_MODE=chunked WHD_HOOK_LOG_DIR=/var/log/webhookd WHD_LOG_MODULES=http,hook WHD_LOG_LEVEL=info sac:$2y$<bcrypt-hash-masked>

A hook is simply an executable script in /opt/webhookd/scripts. The URL path maps to the script name, and the .sh extension is optional in the URL. Create a script and make it executable, and it is immediately callable with the same Basic auth credentials.

sudo tee /opt/webhookd/scripts/deploy.sh >/dev/null <<'EOF' #!/usr/bin/env bash echo "deploying ${app:-demo} to ${env:-staging}" echo "triggered by ${x_forwarded_for:-unknown}" EOF
sudo chmod +x /opt/webhookd/scripts/deploy.sh
sudo chown webhookd:webhookd /opt/webhookd/scripts/deploy.sh

Call it with query parameters. webhookd passes them to the script as environment variables.

WU="$(sudo grep -E '^webhookd\.user=' /root/webhookd-credentials.txt | cut -d= -f2-)" WP="$(sudo grep -E '^webhookd\.pass=' /root/webhookd-credentials.txt | cut -d= -f2-)" curl -k -u "$WU:$WP" 'https://127.0.0.1/deploy?app=web&env=production'

webhookd also converts HTTP headers to snake_case variables and adds built-ins such as hook_name, hook_method, x_forwarded_for and x_webauth_user (the authenticated username). POST bodies are available to the script on standard input.

The per-VM password lives, bcrypt-hashed, in /etc/webhookd/htpasswd. To rotate it or add another user, run htpasswd -B, then restart webhookd so that it reloads the file.

sudo htpasswd -B /etc/webhookd/htpasswd sac
# rotate the sac password
sudo htpasswd -B /etc/webhookd/htpasswd teammate
# add a second user
sudo systemctl restart webhookd

Keep /root/webhookd-credentials.txt in step with any change. Do not empty the htpasswd file back to zero users unless you intend to take the endpoint offline, because with no users every request is refused with HTTP 401.

The image ships a per-VM self-signed certificate at /etc/nginx/certs/cert.pem, with the private key at key.pem. For production, replace it with a certificate for your own domain, for example one issued by Let's Encrypt or your private CA. Then reload nginx.

sudo cp your-fullchain.pem /etc/nginx/certs/cert.pem
sudo cp your-privkey.pem /etc/nginx/certs/key.pem
sudo systemctl reload nginx

Point your callers at your domain name over HTTPS. They then no longer need curl -k.

Restrict the NSG. Allow TCP 443 only from the networks that call your webhooks, and TCP 22 for administration only. webhookd runs shell scripts, so treat the endpoint as privileged.

Keep authentication on. The shipped configuration requires a valid username and password on every hook request. Never point WHD_PASSWD_FILE at a missing file, because that would disable authentication.

Review your hook scripts. Anything a hook script can do runs as the webhookd user. Validate query parameters and request input inside your scripts. Keep the scripts directory writable only by root and the webhookd user.

Set a sensible timeout. WHD_HOOK_TIMEOUT (default 30 seconds in this image) caps how long a hook may run. Raise it only for hooks that genuinely need longer.

Use a trusted certificate. For production callers, replace the per-VM self-signed certificate with one for your domain (Step 10).

Keep the OS patched. Unattended security upgrades remain enabled on the running VM.

webhookd is free and open-source software by Nicolas Carlier and contributors, distributed under the MIT License. This SecureAnyCloud image bundles the unmodified official release binary, verified by sha256.

SecureAnyCloud provides the packaging, the secure-by-default hardening, the mandatory per-VM authentication, the nginx TLS endpoint, the self-test tool, and 24/7 support with a guaranteed 24-hour response SLA.

SecureAnyCloud is not affiliated with or endorsed by the webhookd project or Nicolas Carlier. webhookd is used here only to identify the software.

Deploy on Azure

Find webhookd on Ubuntu 24.04 LTS on the Azure Marketplace, published by SecureAnyCloud. Deploy from the Azure Portal or the Azure CLI as shown above.

Need Help?

Email sales@secureanycloud.com for deployment help, configuration questions or licensing enquiries.

Deploy on Azure

Launch webhookd on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Subscribe to webhookd on AWS Marketplace (published by SecureAnyCloud). Then launch the Ubuntu 24.04 AMI with your key pair and a security group that opens ports 22, 80 and 443 as described above.

First boot generates the per-instance credential and TLS certificate and starts the service. This takes a few seconds after the instance reaches the running state.

SSH in and confirm that webhookd and nginx are active and listening. webhookd owns the loopback port 127.0.0.1:8080, and nginx owns the public ports 80 and 443.

sudo systemctl start webhookd nginx sleep 2 systemctl is-active webhookd nginx

On first boot, the unique username, password and endpoint for this instance are written to a root-owned file. Read them over SSH.

$
sudo cat /root/webhookd-credentials.txt webhookd.user=sac webhookd.pass=<your-per-instance-password> webhookd.host=<public-ip> webhookd.url=https://<public-ip>/ webhookd.example_hook=https://<public-ip>/echo

The password is unique to this instance and never leaves it. Keep the file readable only by root.

webhookd refuses any request that does not carry valid HTTP Basic credentials, so no unauthenticated caller can ever run a hook. A request with no credentials is refused with HTTP 401.

curl -sk -o /dev/null -w 'anonymous request without credentials: HTTP %{http_code}\n' https://localhost/echo

The image ships a fail-closed htpasswd file with zero user entries. If first boot has not yet completed, every hook request is refused rather than left open.

The image includes a self-signed certificate, so pass -k to curl, or install a CA-signed certificate for your domain in production. Call the bundled echo hook with your per-instance credentials, and its output streams back line by line.

$ curl -k -u sac:<your-per-instance-password> https://<public-ip>/echo?name=sac sac webhookd example hook hook_name=echo method=GET authenticated_user= hello, sac step 1/3 working... step 2/3 working... step 3/3 working... done: hook completed successfully

For real-time Server-Sent Events, ask for them with an Accept header.

$ curl -k -u sac:<your-per-instance-password> -H 'Accept: text/event-stream' https://<public-ip>/echo

You can prove the full authentication round trip on the instance itself, without printing any password, with the bundled proof script. It confirms that anonymous and wrong credentials are refused with 401, while the correct per-instance credential returns 200 and runs the hook. It checks both the loopback backend and the nginx TLS edge.

sudo /usr/local/sbin/webhookd-roundtrip.sh

To publish a new webhook, drop an executable script into the hooks directory and call it by name. A script at /opt/webhookd/scripts/deploy.sh becomes the endpoint https://<public-ip>/deploy.

$
sudo tee /opt/webhookd/scripts/deploy.sh >/dev/null <<'SCRIPT' #!/usr/bin/env bash echo "deploying ${ref:-main}..."
# your deployment commands here echo "done" SCRIPT $
sudo chmod +x /opt/webhookd/scripts/deploy.sh $
sudo chown webhookd:webhookd /opt/webhookd/scripts/deploy.sh $ curl -k -u sac:<your-per-instance-password> "https://<public-ip>/deploy?ref=release-1"

Request query parameters (for example ?ref=release-1) and HTTP headers are passed to your script as environment variables, so a hook can act on the payload that triggered it.

Rotate the password at any time, then restart the service to pick it up.

$
sudo htpasswd -B /etc/webhookd/htpasswd sac $
sudo systemctl restart webhookd

Configuration lives in /etc/webhookd/webhookd.env. It holds the listen address, hook directory, htpasswd path, hook timeout and default streaming mode.

To replace the self-signed certificate with a CA-signed certificate for your domain in production, place your certificate and key in /etc/nginx/certs/ as cert.pem and key.pem. Then run sudo systemctl reload nginx.

The service runs under systemd, so it restarts automatically and logs to the journal. Check its status with this command.

systemctl status webhookd --no-pager --lines 0