A webhook endpoint is a URL of yours that the panel POSTs to when something happens: a server is ready, deleted or suspended, a task or a backup finished, a node went offline. With webhooks a billing system does not have to keep polling the API. Each request is signed with the endpoint's own secret.
Who may have webhooks#
Each account adds its own endpoints, up to 10. An endpoint only hears what its owner can see through the API. A reseller's endpoint never gets node details, and a user's endpoint gets only that user's servers.
Which levels may have endpoints is set under System › Settings, on the API tab, in the Webhooks section:
| Setting | Default | What it does |
|---|---|---|
| Who may create webhooks | Administrators, resellers | Levels whose accounts may have endpoints. The endpoints of a level that is not ticked receive nothing. |
| Allow plain HTTP for administrators' endpoints | Off | Resellers' and users' endpoints are always HTTPS. |
| Private networks administrators' endpoints may reach | Empty | Up to 10 networks in the private, CGNAT or unique-local ranges, for example a WHMCS on your LAN (192.168.10.0/24). |
How long deliveries are kept (30 days by default, 7 to 90) is set under System › Settings › Logs (Webhook deliveries).
The webhook worker must be running for anything to be sent. See Workers and queues.
Adding an endpoint#
- Open the user menu, choose Settings, then Webhooks. The panel asks for your password again.
- Click Add endpoint.
- Fill in the form:
- Name: up to 60 characters, unique in your account.
- URL:
https://only (plainhttp://only for administrators, when allowed above), with no user name or password in it. The host is checked when you save and again before every request. - Description: optional, up to 200 characters.
- Events: tick events by group, use All in this group, or switch on All events, including ones added later.
- Enabled: on by default.
- Click Save. The page shows the signing secret once (
whsec_…), with Copy secret. Store it where your receiver verifies signatures. - Click Send test. The panel sends a
webhook.pingevent. Tests are not retried and do not count towards the failing state.
Endpoints can also be managed through the API (/api/v1/webhooks) with the scopes webhooks:read and webhooks:write. Both are in the Read only and Billing system presets.
What the panel refuses as a URL#
To prevent the panel being used to reach internal services, an endpoint's host is resolved and every address is checked. These are refused: loopback, private and unique-local ranges (unless listed in the setting above), link-local and cloud metadata addresses, CGNAT, documentation and reserved ranges, multicast, the panel's own addresses and every node's address. localhost and numeric IPv4 tricks (decimal, octal, hexadecimal) are refused too. Allowed ports are 443, 80 for HTTP, or 1024 and above. The connection is pinned to the address that was checked, so a DNS change between the check and the request cannot redirect it.
The endpoint's page#
Click Open on an endpoint. It has three tabs:
- Overview: the URL, status, events, the last success and the last failure with its reason, and the last 24 hours of deliveries by outcome. The Signing secret section has Rotate secret.
- Deliveries: each event sent, with its request body and each attempt (the address connected to, the HTTP status, the first response headers and 4 KB of the response body, or the error in plain words). Resend sends one again; Resend failed resends up to 500 failed deliveries after a confirmation.
- Settings: the form above.
Administrators see every endpoint of the panel under System › Webhooks (tabs for endpoints and deliveries), and can disable or delete any of them. A user's page has a Webhooks card too.
The request#
Every event is a POST with a JSON body:
{
"id": "evt_01JD3K8Q2V7W0Z5XH6N4Y1C9TB",
"type": "server.ready",
"timestamp": "2026-11-15T09:30:04Z",
"api_version": "v1",
"data": {
"server": { "id": "0193a5b0-…", "hostname": "web-01", "status": "running" },
"task_id": "9b1e…",
"origin": { "via": "api", "api_key": "vmk_7Hq2xYz81aBc" }
}
}
idis the event's ID. A retry or a resend has the sameid; use it to do the work only once.timestampis when the event happened, not when it was sent.dataholds the API's own objects (the server, task, backup, account or node) as the endpoint's owner would get them from the API.origin.viaispanel,apiorsystem.origin.api_keyis filled in only when the key belongs to the endpoint's owner, so a billing system can tell its own actions from others'.- Bodies never contain a password, a key or a sign-in link.
server.password_resetonly says that it happened; read the new password through the API. - Bodies are at most 256 KB. A larger one carries only the subject's
idand"truncated": true; fetch the resource through the API.
The headers:
Content-Type: application/json
webhook-id: evt_01JD3K8Q2V7W0Z5XH6N4Y1C9TB
webhook-timestamp: 1763199004
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
No header or user agent names VMStack, so a white-labelled panel does not reveal itself to its customers' receivers.
Verifying the signature#
Requests follow Standard Webhooks. The signature is v1, followed by the base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>. The HMAC key is the secret's bytes: the base64 part after whsec_. The Standard Webhooks libraries (PHP, Node, Python, Go, Java, Ruby, C#, Rust) verify this in two lines. Without a library, in PHP:
function verify(string $secret, array $headers, string $body): bool
{
$id = $headers['webhook-id'] ?? '';
$timestamp = $headers['webhook-timestamp'] ?? '';
if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
return false; // more than 5 minutes off
}
$key = base64_decode(substr($secret, strlen('whsec_')));
$expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$body}", $key, true));
foreach (explode(' ', $headers['webhook-signature'] ?? '') as $signature) {
[$version, $value] = array_pad(explode(',', $signature, 2), 2, '');
if ($version === 'v1' && hash_equals($expected, $value)) {
return true; // any one listed signature
}
}
return false;
}
Rules for a receiver:
- Verify against the raw body bytes, before any JSON decoding.
- Reject timestamps more than 5 minutes off, and compare in constant time (
hash_equals). - Accept the request if any one of the space-separated signatures matches. During a secret rotation the header carries two.
- Answer with a 2xx within 10 seconds, then do the work. Slow work in the request handler causes timeouts and retries.
- De-duplicate on
id. Delivery is at least once: the same event can arrive twice. - Do not rely on order. A retry can be overtaken by later events. When order matters, compare the resource's
updated_ator fetch it with the API.
Rotating the secret#
- Open the endpoint and click Rotate secret.
- Under Keep the old secret signing for, choose None, 1 hour, 24 hours (the default) or 7 days.
- Copy the new secret (shown once) and roll it out to your receiver.
While the overlap lasts, every request carries both signatures, the new one first. If a secret is lost, rotate it; it cannot be shown again.
Retries and failing endpoints#
- Success is any 2xx answer. Everything else is a failure: a 3xx (redirects are never followed), 4xx, 5xx, a timeout (3 seconds to connect, 10 seconds in all), a TLS error, or an address the URL check refuses at send time.
- Retries: 8 attempts in all: at once, then 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours after the previous attempt, each ±10 %. After the 8th failure the delivery is failed. A delivery not settled 72 hours after its event expires.
429or503withRetry-After: the next attempt waits at least that long, at most an hour.410 Gonedisables the endpoint at once and cancels its pending deliveries.- Only one request is in flight per endpoint at a time.
- Failing: after 3 failures in a row an endpoint is failing. Only its oldest delivery is tried, 1, 5 and 15 minutes later and then every 30 minutes. The others wait, which does not use up their attempts. One success sends the waiting deliveries, oldest first.
- The owner is mailed after an endpoint has been failing for an hour (Webhook endpoint failing, optional). After 24 hours and at least 20 failures in a row the endpoint is disabled and the owner is mailed (Webhook endpoint disabled). It also shows on the administrators' dashboard.
To bring a disabled endpoint back, fix the receiver, open the endpoint and click Enable. You can tick the option to also resend the deliveries cancelled when it was disabled.
Events#
96 event types in ten groups. Each endpoint chooses events one by one, by group, or all (*, which includes event types added later). Only the events an account's level is offered appear in its form. The bodies of each event are in the Webhooks sections of the API reference.
A = administrator, R = reseller, U = user.
Servers#
| Event | Who | When |
|---|---|---|
server.created |
A R U | A server was accepted and is being built. |
server.setup_completed |
A R U | A server waiting for its owner was set up and is being built. |
server.ready |
A R U | A server was built and runs. |
server.create_failed |
A R U | A server could not be built. |
server.deleted |
A R U | A server was deleted (or its create cancelled). |
server.delete_failed |
A R U | A server could not be deleted. |
server.reinstalled |
A R U | A server was reinstalled. |
server.reinstall_failed |
A R U | A reinstall failed. |
server.application_ready |
A R U | The application (or the recipes) a server runs at its first boot finished. |
server.application_failed |
A R U | The application (or a recipe) a server runs at its first boot failed. |
server.state_changed |
A R U | A server started, stopped, entered or left rescue, or went into error. |
server.suspended |
A R U | A server was suspended (by staff or for its traffic). |
server.unsuspended |
A R U | A suspension was lifted. |
server.expiring |
A R U | A server expires soon and its owner was told (sent once per expiry). |
server.expired |
A R U | A server expired and was suspended or is being deleted. |
server.expiry_changed |
A R | The expiry of a server was set, extended or removed. |
server.renamed |
A R U | A server got a new hostname. |
server.upgraded |
A R U | A server got more vCPUs, memory or disk. |
server.upgrade_failed |
A R U | An upgrade failed. |
server.owner_changed |
A R U | A server was given to another account. |
server.move_started |
A R | An administrator started moving a server to another node. |
server.ha_recovered |
A R U | High availability started a server on another node after its node died. |
server.moved |
A R U | A server was moved to another node and runs there; its addresses may have changed. |
server.move_failed |
A R | A move to another node failed or was cancelled; the server is back on its node. |
server.addresses_changed |
A R U | A server's node routes a new list of addresses. |
server.password_reset |
A R U | A server's root password was reset (read it with the API). |
server.traffic_threshold |
A R U | A server used 80 % or 100 % of its traffic. |
server.throttled |
A R U | A server's speed was limited for its traffic. |
server.throttle_ended |
A R U | A speed limit for traffic ended. |
server.limits_changed |
A R U | A server's node took new CPU limits or disk I/O limits. |
server.disk_added |
A R U | An extra disk was added to a server. |
server.disk_resized |
A R U | An extra disk of a server grew. |
server.disk_attached |
A R U | An extra disk was enabled: attached now or at the next start. |
server.disk_detached |
A R U | An extra disk was disabled: detached now or at the next power off. |
server.disk_deleted |
A R U | An extra disk was deleted. |
server.disk_failed |
A R U | A change of an extra disk failed on the node. |
server.disk_moved |
A | An administrator moved a disk of a server to another storage of its node. |
server.disk_move_failed |
A | A move of a disk to another storage failed; the disk is where it was. |
server.cloned |
A R U | A server was made as a copy of another server and runs. |
server.private_network_attached |
A R U | A server was put on a private network. |
server.private_network_detached |
A R U | A server is being taken off a private network. |
server.domain_added |
A R U | A website domain was added to a server behind NAT; it waits for its TXT record. |
server.domain_verified |
A R U | A website domain of a server behind NAT was verified and is served on ports 80 and 443. |
server.domain_removed |
A R U | A website domain of a server behind NAT was removed. |
server.floating_ip_attached |
A R U | A floating IP is being given to a server. |
server.floating_ip_detached |
A R U | A floating IP is being taken off a server; it stays its account's. |
abuse.detected |
A R | Abuse detection found a server sending spam, flooding, scanning, or keeping its CPU or disks busy for longer than its policy allows. |
abuse.actioned |
A R | A server's abuse policy acted: outbound mail blocked, speed limited, or suspended. |
abuse.cleared |
A R | An administrator cleared an abuse event (a throttle it placed is lifted). |
Tasks#
| Event | Who | When |
|---|---|---|
task.succeeded |
A R U | A task finished. |
task.failed |
A R U | A task failed. |
task.cancelled |
A R U | A task was cancelled, before it was sent to its node or while it ran. |
Backups#
| Event | Who | When |
|---|---|---|
backup.completed |
A R U | A backup finished. |
backup.failed |
A R U | A backup failed. |
backup.restored |
A R U | A server was restored from a backup. |
backup.restore_failed |
A R U | A restore failed. |
backup.deleted |
A R U | A backup was deleted. |
backup.verified |
A | A verify of a backup ended: whole, or the problems it found. |
backup.expiry_changed |
A R U | A backup is kept until a date, forever, or as its schedule says again. |
backups.paused |
A | Scheduled backups were paused, for the panel, a node or a destination, with a reason. |
backups.resumed |
A | Scheduled backups were resumed. |
Snapshots#
| Event | Who | When |
|---|---|---|
snapshot.completed |
A R U | A snapshot was taken. |
snapshot.failed |
A R U | A snapshot could not be taken. |
snapshot.reverted |
A R U | A server was reverted to a snapshot. |
snapshot.revert_failed |
A R U | A revert to a snapshot failed. |
snapshot.deleted |
A R U | A snapshot was deleted (by hand or when it expired). |
Accounts#
| Event | Who | When |
|---|---|---|
user.created |
A R | An account you manage was created. |
user.updated |
A R | An account you manage was changed. |
user.suspended |
A R | An account you manage was suspended. |
user.unsuspended |
A R | An account you manage was unsuspended. |
user.deleted |
A R | An account you manage was deleted. |
user.locked_out |
A R | An account you manage was banned from signing in for a while, after failed sign-ins. |
user.member_added |
A R | A login joined the team of a customer you manage. |
user.member_removed |
A R | A login was removed from the team of a customer you manage, or left it. |
user.member_role_changed |
A R | A team member of a customer you manage got another role. |
Nodes#
| Event | Who | When |
|---|---|---|
node.offline |
A | A node stopped answering. |
node.online |
A | A node answers again. |
node.agent_updated |
A | A node's agent was updated. |
node.agent_update_failed |
A | An agent update failed or was rolled back. |
node.new_servers_stopped |
A | An administrator stopped new servers on a node. |
node.new_servers_allowed |
A | A node takes new servers again. |
node.maintenance_started |
A | A node went into maintenance. |
node.maintenance_ended |
A | A node's maintenance ended. |
node.ha_dead |
A | High availability found a node dead; its protected servers are started on other nodes. |
node.evacuation_started |
A | An administrator started emptying a node. |
node.evacuation_finished |
A | Emptying a node ended: done or cancelled, with how many servers moved. |
Backup destinations#
| Event | Who | When |
|---|---|---|
backup_destination.check_failed |
A | A backup destination failed its check. |
backup_destination.read_only_changed |
A | A backup destination was made read-only, or writable again. |
Security#
| Event | Who | When |
|---|---|---|
security.address_locked_out |
A | An address was banned from signing in for a while, after failed sign-ins. |
Images#
| Event | Who | When |
|---|---|---|
image.captured |
A | An image was made from a server and is ready on its node. |
image.capture_failed |
A | An image could not be made from a server. |
Networks#
| Event | Who | When |
|---|---|---|
loadbalancer.created |
A R U | A load balancer was made; its node starts it. |
loadbalancer.updated |
A R U | A load balancer's settings, servers, certificate or node changed. |
loadbalancer.deleted |
A R U | A load balancer was deleted; its address is free again. |
loadbalancer.backend_down |
A R U | A server behind a load balancer failed its health check: no new connections go to it. |
loadbalancer.backend_up |
A R U | A server behind a load balancer passes its health check again and is back in rotation. |
The test event webhook.ping is sent only by Send test (or POST /api/v1/webhooks/{id}/ping), whatever the endpoint subscribes to.