What the webhook trigger does
Home Assistant can start an automation when an HTTP request arrives at a webhook URL. That makes almost anything a trigger: an iOS Shortcut, a script on another machine, a door sensor with its own firmware, or a service on the internet.
Create a webhook automation
- Go to Settings → Automations & scenes → Create automation.
- Add a trigger and choose Webhook. Home Assistant generates a webhook ID.
- Open the trigger's settings to choose the allowed methods (POST and PUT by default) and whether it is only accessible from the local network (on by default).
- Add your actions and save.
The URL is your Home Assistant address plus the ID:
http://homeassistant.local:8123/api/webhook/<webhook_id>In YAML, the same automation looks like this:
triggers:
- trigger: webhook
webhook_id: "garage-7f3k2q9xw4"
allowed_methods:
- POST
local_only: true
actions:
- action: notify.notify
data:
message: "Garage says: {{ trigger.json.message }}"Read data from the request
The request is available to templates:
| Variable | Contains |
|---|---|
trigger.json | The parsed JSON body. |
trigger.data | Form fields, for form-encoded bodies. |
trigger.query | Query string parameters. |
trigger.webhook_id | Which webhook fired. |
Test it with curl:
curl -X POST -H "Content-Type: application/json" \
-d '{"message": "door opened"}' \
http://homeassistant.local:8123/api/webhook/garage-7f3k2q9xw4Security: the ID is the password
Webhook triggers don't need a Home Assistant login or token. The webhook ID is the only secret, so:
- Use a long, random ID, not
garageortest. - Keep local only on for anything that doesn't need the internet.
- Treat the URL like a password; see what a webhook URL is.
- Don't let a webhook unlock doors or disarm alarms on its own say-so.
Reach Home Assistant from the internet
With local only switched off, a webhook still needs a public address. The simplest is Home Assistant Cloud (Nabu Casa): under Settings → Home Assistant Cloud → Webhooks, enable a webhook to get a public https://hooks.nabu.casa/… URL for it, without opening ports on your router. A reverse proxy with HTTPS works too, if you already run one.
Send webhooks from Home Assistant
To call another service when something happens at home, use the rest_command integration:
rest_command:
notify_backend:
url: "https://example.com/hooks/home"
method: post
content_type: "application/json"
payload: '{"entity": "{{ entity }}", "state": "{{ state }}"}'Then call rest_command.notify_backend as an action in any automation.
Use signed webhooks from the internet safely
Services like GitHub or Stripe sign their webhooks, but Home Assistant's webhook trigger can't check those signatures, and a home internet connection isn't always up. HookStead can sit in between:
- Point the service at a HookStead source. It verifies the signature (see webhook signatures) and stores the event.
- Add your Home Assistant Cloud webhook URL as a destination. HookStead forwards the original JSON body, so
trigger.jsonworks as usual. - If your home connection is down, HookStead keeps retrying, and you can replay any event later.
HookStead only delivers to public addresses, so this works with a Home Assistant Cloud URL or your own public HTTPS address, not with homeassistant.local.
Frequently asked questions
- What is the Home Assistant webhook URL?
- Your Home Assistant address followed by /api/webhook/ and the webhook ID, for example http://homeassistant.local:8123/api/webhook/<id>.
- Do Home Assistant webhooks need authentication?
- No. The webhook ID is the only secret, so make it long and random, and keep local-only on unless you need access from the internet.
- How do I read the JSON body in a Home Assistant webhook automation?
- Use trigger.json in templates, for example {{ trigger.json.message }}. Form fields are in trigger.data and query parameters in trigger.query.