Webhooks and events
Valet watches your services by asking them. Two doors let it work the other way round:
- Webhooks in. A service, a script or a cron job tells Valet that something happened, with one POST. It shows as a notice on the page, goes on the timeline, can reach your phone, and can set off a rule.
- Events out. What Valet notices (a service going down, a download finishing, a backup failing) goes to a webhook or an MQTT broker, so something else can act on it.
Both are off until you set them up.
Webhooks in
Section titled “Webhooks in”Name a hook and give it a token of its own:
hooks: backup: { token: "${BACKUP_HOOK}" }BACKUP_HOOK=paste-the-output-of-openssl-rand-hex-32Then, from anywhere on your network:
curl -X POST http://valet:7575/hooks/backup \ -H "Authorization: Bearer $BACKUP_HOOK" \ -d "Nightly backup done: 4.2 GB"A toast says Nightly backup done: 4.2 GB on every open page, and the timeline records that the hook fired.
What it says
Section titled “What it says”Without text, a hook says what it was sent: plain words, or the text, message, msg or title field of JSON. With nothing to say, it says its own name. With text, you choose the words, and {dotted.path} fills in from the JSON:
hooks: sonarr: { token: "${SONARR_HOOK}", text: "{series.title} downloaded", sub: "{episodes.0.title}", tone: good }A field that isn’t there is left empty. {episodes.0.title} is the first episode’s title. Only words, numbers and true or false fill in; a whole object or list is left empty.
| Option | Default | |
|---|---|---|
token | required | At least 32 characters, from .env. Each hook needs its own. |
text | what it was sent | The notice. {dotted.path} fills in from the JSON. |
sub | none | A quieter second line, filled the same way. |
tone | accent | good, warn, bad or accent. |
push | false | Also send it to your notification channels and to the devices with notifications on. |
rate | 30 | Calls a minute at most. |
query | false | Also take the token in the address, ?token=…. See below. |
Sending the token
Section titled “Sending the token”Any one of these works:
Authorization: Bearer <token>.- Basic auth with the token as the password and any user name. This is what Sonarr’s and Radarr’s webhook settings offer.
X-Valet-Token: <token>, for a tool that can set a header but notAuthorization.
What it answers
Section titled “What it answers”| Answer | When |
|---|---|
200 {"ok":true} | It was heard. |
401 | No token, a wrong one, another hook’s, a hook that isn’t there, or no hooks at all. All the same, so nobody can find out which hooks exist. |
405 | The right token, but not a POST. |
413 | A body over 16 KB. |
429 | More than rate calls in a minute. Retry-After says when to try again. |
The body can be JSON, a form, or plain words. JSON is read as JSON whatever the Content-Type says, because curl -d calls everything a form.
Examples
Section titled “Examples”Sonarr and Radarr. Settings, Connect, add a Webhook. URL http://valet:7575/hooks/sonarr, method POST, any user name, and the token as the password. Choose the events you want (On Import, On Health Issue).
hooks: sonarr: { token: "${SONARR_HOOK}", text: "{series.title} downloaded", sub: "{episodes.0.title}", tone: good } radarr: { token: "${RADARR_HOOK}", text: "{movie.title} ({movie.year}) downloaded", tone: good }Uptime Kuma. Settings, Notifications, add a Webhook. URL http://valet:7575/hooks/kuma, body Preset - application/json, and under Additional Headers:
{ "Authorization": "Bearer your-kuma-hook-token" }hooks: kuma: { token: "${KUMA_HOOK}", text: "{msg}", tone: bad, push: true }Home Assistant. A rest_command, called from any automation:
rest_command: tell_valet: url: http://valet:7575/hooks/home method: POST headers: { Authorization: !secret valet_hook } # "Bearer <token>" in secrets.yaml content_type: application/json payload: '{"text": "{{ text }}"}'hooks: home: { token: "${HOME_HOOK}" }A cron job that only speaks when something goes wrong:
0 3 * * * /usr/local/bin/backup.sh || curl -s -H "Authorization: Bearer $BACKUP_HOOK" -d "The nightly backup failed" http://valet:7575/hooks/backupA rule that waits on a hook
Section titled “A rule that waits on a hook”A rule can be set off by a hook, instead of by a card or a time of day: “whenever the Sonarr hook fires, pause the downloads”. Ask in chat, approve the card, and it runs every time that hook is called, at most once per cooldown.
Nothing the caller sends reaches the rule’s action. The tool and its input are the ones on the card you approved, and the hook passes on only its name. A rule set off by a hook is held to everything any rule is: one integration tool, never the config or Valet’s own tools, and checked again against assistant.access before every run. Take the hook out of the config and its rules can’t run; their card says why. See rules.
What a hook’s words can’t do
Section titled “What a hook’s words can’t do”What a hook sends is another program’s words, so Valet treats them that way:
- Never to a model. The notice and the timeline card show them to you. The timeline line the assistant reads says only The backup hook fired. The brief, the suggestions and rules never see them.
- Never as a page. The notice is drawn as plain text, so
<script>is only words. Each line is cut to 200 characters, with line breaks and invisible control characters taken out. - Never past the payload. A template reads only fields the JSON itself holds, so a path like
{__proto__.x}or{constructor.name}is empty. - Secrets are taken out. Like everything Valet shows, the words pass through the redactor.
The token in the address
Section titled “The token in the address”Some senders can only be given an address. For those, query: true also takes the token as ?token=…. An address gets written down in places a header doesn’t: the sender’s own settings and logs, a proxy’s access log, a browser’s history. Use it only when there’s no other way, give that hook its own token, and nothing more than a notice.
Events out
Section titled “Events out”events: targets: - { type: mqtt, url: mqtt://mosquitto:1883, username: valet, password: "${MQTT_PASSWORD}" } - { type: webhook, url: http://nodered:1880/valet, secret: "${EVENTS_SECRET}" }Every event is one small JSON document. It goes to each target that takes its type: events.on chooses for all of them, and a target’s own on narrows that.
events: on: [service, backup, hook] targets: - { type: webhook, url: http://nodered:1880/valet, on: [service] } - { type: mqtt, url: mqtt://mosquitto:1883 }What’s published
Section titled “What’s published”Every event has type and at (an ISO time, UTC). A second line of words, when there is one, is detail. Long words are cut at 500 characters, and every secret Valet knows is taken out first.
type | When | Fields |
|---|---|---|
service | A service on a status card goes down or comes back: the same detection as live.notify, for every status card on the page. | state (down or up), name, widget, detail |
activity | Something starts or finishes on a card: a stream, a download, a robot cleaning. | state (start or end), widget, title, detail |
notice | Any notice the page shows: live.notify, reminders, rules, backups, meetings, hooks. | text, detail, tone, source (the widget or hook it’s about) |
backup | A backup job goes wrong, or comes right. | state (problem or recovered), name, source, health (failed, overdue, ok…), text, detail |
rule | A rule runs, fails or pauses itself. | id, ok, text, detail |
hook | A hook is called. | name, text, detail, tone |
ask | An MCP client asks to change something and waits for your approval. | id, from, tool, title |
{"type":"service","at":"2026-11-03T09:30:00.000Z","state":"down","name":"Plex","widget":"services.status","detail":"connection refused"}{"type":"activity","at":"2026-11-03T21:04:12.000Z","state":"end","widget":"downloads.active","title":"Ubuntu 26.04 ISO"}A notice is often a second telling of something with its own event, like a service going down with live.notify on. Choose the types you want with on.
To a webhook
Section titled “To a webhook”Each event is a POST of its JSON, with its type in X-Valet-Event. With secret (16 characters or more), the body is signed so the receiver can check it came from Valet:
X-Valet-Signature: sha256=<the hex HMAC-SHA256 of the raw body, keyed with the secret>To check it, in Node:
import { createHmac, timingSafeEqual } from 'node:crypto';const ok = (body, header) => { const want = Buffer.from(`sha256=${createHmac('sha256', process.env.EVENTS_SECRET).update(body).digest('hex')}`); return header?.length === want.length && timingSafeEqual(Buffer.from(header), want);};A receiver that can’t be reached, or answers 429 or 5xx, is tried again with a pause that doubles up to five minutes. Any other refusal means it doesn’t want that one, and it’s let go.
| Option | Default | |
|---|---|---|
url | required | http:// or https://. |
headers | none | Sent with each, like { Authorization: "Bearer ${TOKEN}" }. |
secret | none | Signs each body. |
on | events.on | Only these types. |
To an MQTT broker
Section titled “To an MQTT broker”Valet publishes under topic (valet by default):
| Topic | What | Retained |
|---|---|---|
valet/status | online while Valet is connected, offline when it stops. The broker says offline itself if Valet vanishes. | yes |
valet/service/<name> | A service’s latest service event. | yes |
valet/activity/<widget> | A card’s latest activity event. | yes |
valet/backup/<job> | A job’s latest backup event. | yes |
valet/hook/<name>, valet/rule/<id> | Each time one fires. | no |
valet/notice, valet/ask | Each one. | no |
A name in a topic is lowercase, with anything that isn’t a letter or a number as -: Home Assistant is home-assistant. A retained topic means something that starts listening later still hears the current state. Set retain: false to keep nothing on the broker.
For a Home Assistant sensor of whether Plex is up:
mqtt: binary_sensor: - name: Plex state_topic: valet/service/plex value_template: "{{ value_json.state }}" payload_on: "up" payload_off: "down" device_class: connectivity availability_topic: valet/status| Option | Default | |
|---|---|---|
url | required | mqtt://host:1883, or mqtts://host:8883 for TLS. |
username, password | none | The password from .env. |
topic | valet | Everything goes under it. |
retain | true | Keep the latest state on the broker. |
qos | 0 | 1: the broker acknowledges each message, and one that wasn’t acknowledged is sent again after a reconnect. |
clientId | valet- and random letters | |
keepalive | 60 | Seconds between pings. |
on | events.on | Only these types. |
Valet only publishes. It never subscribes, so nothing on the broker can tell it to do anything.
When a target is down
Section titled “When a target is down”Nothing waits on a target. A page loads, a rule runs and a notice shows whether a target is up or not. While one can’t be reached, up to 200 events wait for it, oldest let go first. It’s tried again with a growing pause, and the log says so once when it fails and once when it’s back.
A config reload keeps a broker’s connection if events didn’t change. If it did, the old connection says offline and closes before the new one opens. config check reads the settings without connecting to anything.
Neither hooks nor events run in a sandbox.