Help / Alerts
Webhooks
A webhook channel sends each alert as JSON to a web address you choose. Use it to feed alerts into your own systems, chat bots or scripts.
What you need first
- An address that accepts a POST request with a JSON body. It must start with
https://and be reachable from the internet. - A confirmed account. Until you confirm your own email address, alerts can only go to that address by email.
Set it up
- Open Alerts and go to Add a channel.
- Under Where should alerts go?, choose Webhook.
- In Send to, enter your address, for example
https://example.com/hook. - If you like, fill in Label (optional).
- Tick the events to send: Down, Back up, Certificate expiring and Slow.
- Press Add channel.
We do not sign webhook requests. Use an address with a long random part in it, so nobody can guess it and send you fake alerts.
What we send
Each alert is one POST request with Content-Type: application/json. A down alert looks like this:
{
"event": "down",
"at": "2026-11-16T09:30:12Z",
"detail": "HTTP 503\nSeen from: Frankfurt, London",
"url": "https://example.com/monitors/42",
"monitor": {
"id": 42,
"name": "Shop",
"type": "http",
"target": "https://shop.example.com",
"status": "down"
}
}
| Field | What it holds |
|---|---|
event | What happened: down, up, ssl (certificate expiring), slow, dns (a DNS answer changed) or test. |
at | When the alert was made, in UTC. |
detail | The reason in plain words. It can run over several lines. A back up alert usually says how long the monitor was down and what the cause was. |
url | The monitor's page in HonkWatch. |
monitor.type | One of http, api, keyword, ping, tcp, udp, dns, ssl, domain, thirdparty, pageload or heartbeat. |
monitor.status | The monitor's status when the alert was sent. |
The dns event follows the Down tick.
Maintenance notices
When a maintenance window starts or ends, webhook channels also get a notice, if the window has Tell people when it starts and ends ticked (it is by default). It has a maintenance object instead of monitor:
{
"event": "maintenance_start",
"at": "2026-11-16T22:00:00Z",
"detail": "Planned maintenance on Shop has started, until 16 Nov 2026, 23:00 UTC.",
"url": "https://example.com/maintenance",
"maintenance": {
"id": 7,
"title": "Database upgrade",
"starts_at": "2026-11-16T22:00:00Z",
"ends_at": "2026-11-16T23:00:00Z",
"monitors": ["Shop"]
}
}
The end notice has "event": "maintenance_end". Write your code to look at event first and to ignore values it does not know.
Send a test
- In the channel list on Alerts, press Send test on the webhook row.
- Your address gets a request with
"event": "test". The monitor in it is a made-up one:"id": 0,"name": "Test monitor", targethttps://example.com. Itsurlis the HonkWatch home page, not a monitor page. - Check Recently sent at the bottom of the Alerts page to see whether it was accepted.
How delivery works
- Your server should answer with a 2xx status code. A 4xx or 5xx answer counts as a failure.
- We wait up to 10 seconds for an answer.
- Each alert is sent once. A failed request is not retried, so if your server was down at that moment, the alert is lost for that channel.
- Use the final address of your endpoint. Do not rely on a redirect: a redirect to a private address is refused, and a redirected POST may not arrive as a POST.
- Addresses on private or local networks are refused.
Because of this, keep a second channel such as email for down alerts.
Webhooks through the API
Instead of adding a channel here, tools such as Make or n8n can subscribe to alerts with your API key, using POST /api/v1/hooks. These subscriptions get the same JSON for monitor alerts. They do not get tests or maintenance notices. See API keys and the API.
If it does not work
- You see "That needs an https:// address". Plain
http://addresses are not accepted. Put your endpoint behind HTTPS. - Recently sent shows failed with "Not allowed". The address points to a private or local network, or redirects to one. Use a public address.
- Recently sent shows failed with an HTTP error. Your server answered with an error code. Look at your server's logs for the request.
- Recently sent shows failed with a timeout. Your server took longer than 10 seconds. Answer straight away and do slow work after you reply.
- The address was wrong. A channel cannot be edited. Add a new webhook channel, test it, then press Remove on the old one.
Still stuck? Email [email protected] and say which guide you were following.