Event hooks

HF Panel raises an event each time something happens on the server: a hosting account is created, a domain is removed, a backup finishes, a staff member signs in. You can send these events to your own systems with webhooks, or run your own programs on the server with script hooks. Both get the same JSON payload.

Where: Server Admin › System › Plugins & hooks

Hooks never hold up the person who did the action: they run in the background, and a hook that fails is written to a log, never shown as an error.

Events

The Events tab of the screen shows each event with an example payload.

The payload

Every event is one JSON object. These fields are always there:

The event's own fields follow. For example:

{
  "id": "6f1c2a9e0b7d4c35",
  "event": "account.created",
  "time": "2026-10-25T08:00:00Z",
  "server": "panel.yourdomain.com",
  "actor": "admin",
  "account": "sarahbakes",
  "account_id": 3,
  "email": "sarah@example.com",
  "package": "Basic",
  "domain": "sarahbakes.co.uk",
  "reseller": ""
}

Note: a payload never holds a password, a secret, a token or a key. HF Panel removes any field with such a name before it sends the event.

Webhooks

A webhook sends the events you choose to an address of yours, as a POST with the payload as its body.

Add a webhook

1. Open Plugins & hooks and click the Webhooks tab.
2. Enter the Address (https://), tick the Events it should get (or click All events), and keep On ticked.
3. Click Add webhook. The message at the top shows the webhook's signing secret once. Keep it in your receiving program.

To see the secret again, click Show secret. To replace it, click New secret: the old one stops working at once. Both are written to the activity log.

What HF Panel sends

POST /hostfog HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
User-Agent: HF Panel hooks
X-HF-Event: account.created
X-HF-Delivery: 42
X-HF-Timestamp: 1792915200
X-HF-Signature: sha256=9b2f0c…

{"account":"sarahbakes","account_id":3,"actor":"admin","event":"account.created",…}

Check the signature

Work out the HMAC-SHA256 of the body exactly as you received it, with the signing secret as the key, and compare it with the header in constant time. Refuse the request when they differ. To refuse old requests sent again, also check that the payload's time is recent.

<?php
$secret = 'whsec_…';
$body = file_get_contents('php://input');
$sig = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($sig, $_SERVER['HTTP_X_HF_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
// … do your work, then answer quickly with any 2xx status
http_response_code(204);

import hashlib, hmac

def valid(secret: str, body: bytes, header: str) -> bool:
    sig = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, header)

Retries and the delivery log

• An answer with a 2xx status counts as delivered. Answer within 10 seconds: a slower answer counts as a failure.
• A network error, a 5xx, 408 or 429 is tried again 3 times: after 10 seconds, 1 minute and 5 minutes. Any other answer (for example 404) fails at once.
• Redirects are not followed.
• The Deliveries card shows the last 100 deliveries: when, the event, the address, the status (sent, retry, failed), the attempts and the answer's status code. The body of your answer is never stored.
• Click Send test to send a hook.test event to one webhook at once (one attempt, no retries).

Addresses you can use

The address must start with https:// and point at a public address. HF Panel refuses private, loopback, link-local and reserved addresses (for example 127.0.0.1, 10.0.0.0/8, 192.168.0.0/16, 169.254.169.254, ::1) and names such as localhost, both when you save the address and each time it connects, so a name that points at such an address later is refused too. An address with a user name or password in it is refused. You can have up to 20 webhooks.

Script hooks

A script hook is a program you put on the server as root. It runs as root for each event, with the payload on its standard input.

Add a script hook

1. Make a folder for the event, owned by root: install -d -m 755 /etc/hostfog/hooks/account.created.d

2. Put an executable file in it, owned by root, that only root can change:

   bashCopy

   cat >/etc/hostfog/hooks/account.created.d/10-welcome.sh <<'SH'
   #!/bin/sh
   payload="$(cat)"
   echo "$payload" >>/var/log/new-accounts.json
   SH
   chmod 755 /etc/hostfog/hooks/account.created.d/10-welcome.sh
   

3. Open the Script hooks tab to check that its status is Runs.

How script hooks run

• The files of a folder run one after the other, in name order (start their names with 10-, 20- … to choose).
• Each file gets the payload on its standard input and in the file named by $HF_PAYLOAD_FILE, and the event's name in $HF_EVENT. Nothing else from the panel's environment is passed on.
• A file may run for 30 seconds; then it is stopped. Its exit status and what it prints (up to 64 KB) are written to /var/log/hostfog-hooks.log. The end of that log is shown on the Script hooks tab.
• Script hooks run on the main HF Panel server, also for accounts on other servers of a cluster.

A file is skipped, and the tab says why, when it:

Warning: a script hook runs as root. Never let anyone else write to /etc/hostfog/hooks, and treat the payload's text as data: quote it, and never pass it to a shell as a command.

Related

• Plugins
• Plugins & hooks screen
• Webhooks