Webhooks explained: notify other systems of server events
On this page
A webhook tells another system what happens on the server. For each event you choose, the server sends a signed JSON message to your address — for example to update your billing system when an account is suspended, or to post in a chat channel when a task fails.
Add a webhook
- Log in to the administrator panel (
https://<server>:2087). - Open Webhooks in the menu (section Account).
- Under Add webhook, enter the Address, for example
https://billing.example.com/hooks/hosting. - Tick the Events you want (the account events are ticked by default).
- Click Add webhook.
- The Signing secret is shown. Copy it into the receiving system.
Click Send test to send a test message, Show secret to see the secret again and Remove to delete the webhook.
Events
| Event | When |
|---|---|
account.created | Account created |
account.suspended / account.unsuspended | Account suspended or unsuspended |
account.terminated | Account terminated |
account.changed | Package, contact email, domain or username changed |
account.password | Account password changed |
domain.added / domain.removed | Addon, subdomain or alias added or removed |
domain.moved | Domain moved to another account |
email.created / email.deleted | Mailbox created or deleted |
disk.limit | Account near or over its disk space |
bandwidth.limit | Account over its monthly bandwidth |
task.failed | A server task failed |
ticket.opened / ticket.replied | A customer opened or replied to a support ticket |
What your system receives
A POST request with a JSON body:
Content-Type: application/json
X-Sahaab-Event: account.created
X-Sahaab-Signature: sha256=<HMAC-SHA256 of the body with the secret>
{"event": "account.created", "id": "…", "time": "…", "server": "server1.example.com",
"data": {"account": {"username": "…", "domain": "…", "owner": null}, "package": "…", "email": "…"}}
To check that a message is genuine, compute the HMAC-SHA256 of the raw body with the signing secret and compare it with X-Sahaab-Signature.
Delivery and retries
- Answer with any 2xx status.
- Other answers and timeouts (10 seconds) are tried again after 1, 5, 30 and 120 minutes; after that the delivery is given up.
- Recent deliveries on the page shows each message with its status and, for failures, the error and the number of attempts.
Good to know
- Up to 20 webhooks.
- The address must be complete, starting with
https://(orhttp://), and its name must resolve. - Resellers can add their own webhooks for events of their accounts.
Common questions
My endpoint receives nothing. What should I check?
Click Send test and look at Recent deliveries: the error shows whether the address could not be reached, timed out or answered with an error status.
Thank you — this helps us improve the article.
Still stuck?
Ask the AI about your exact situation — it answers from this knowledge base — or contact us.
Related articles
- How to create an API token for billing and automation
Create an administrator API token, limit it to IP addresses, an expiry date or read-only access, and connect a billing system on port 2087.
- How to find and retry a failed task (Task Queue)
Every change on the server runs as a task. See queued, running, done and failed tasks, read a task's output and run a failed task again.
- Mail server settings: spam filter, sending limits and mail queue
Set the server-wide spam filter and greylisting, limit emails per hour per account, and retry or delete messages waiting in the mail queue.