Webhook

The Webhook trigger is useful when another app or service needs to start an automation in Home Assistant. Each webhook has its own secret address. When an app or service sends a web request to that address, the trigger reacts. For example, a build server can let you know that a build failed, or a phone shortcut can start a scene.

Using this trigger from the user interface

If you prefer building automations visually, Home Assistant walks you through this trigger step by step. You pick what to watch, tweak a few options, and save. No YAML knowledge required.

To use this trigger in an automation:

1. Go to Settings > Automations & scenes.
2. Open an existing automation, or select Create automation > Create new automation.
3. In the When section, select Add trigger.
4. Search for and select the Webhook trigger.
   • Result: Home Assistant fills in a Webhook ID that’s hard to guess.
5. To copy the address of the webhook, select Copy URL to clipboard .
   • Use this address in the app or service that should start the automation.
6. Optional: To change which requests the webhook accepts, select Webhook settings .
   • Select the request methods to allow: GET, HEAD, POST, or PUT.
   • To accept requests from outside your local network, turn off Only accessible from the local network.
7. Select Save.

Options in the UI

Using a webhook with Home Assistant Cloud

With Home Assistant Cloud, a webhook gets a public address. Apps and services can then reach it from anywhere, without opening your Home Assistant to the internet.

1. In the automation, select Webhook settings on the trigger, and turn off Only accessible from the local network. Then, select Save.
   • Requests through Home Assistant Cloud don’t count as local, so the webhook must accept requests from outside your local network. Webhooks that only accept local requests don’t appear in the list of Home Assistant Cloud webhooks.
2. Go to Settings > Home Assistant Cloud, and select Webhooks.
3. Next to your automation, turn on the switch.
   • Result: A dialog shows the Public address of the webhook.
4. Use the public address in the app or service. To see the address again later, select Manage next to the automation.

Sending a request to a webhook

To start the automation, send a web request to the address of the webhook, for example, with the curl command line program. In the examples, replace the address with the one you copied with Copy URL to clipboard. This example sends form data with a POST request:

curl -X POST -d 'key=value&key2=value2' \
  http://YOUR_HOME_ASSISTANT_ADDRESS/api/webhook/YOUR_WEBHOOK_ID

To send JSON data, set the Content-Type header to application/json:

curl -X POST -H "Content-Type: application/json" -d '{ "key": "value" }' \
  http://YOUR_HOME_ASSISTANT_ADDRESS/api/webhook/YOUR_WEBHOOK_ID

Use an HTTPS address if you’ve secured your Home Assistant with SSL/TLS.

The automation can use the data of the request in templates. Form data is in trigger.data, JSON data is in trigger.json, and URL query parameters are in trigger.query. For all properties, refer to Webhook triggers.

Using this trigger in YAML

If you work directly in YAML, or you want to know exactly what Home Assistant does under the hood, this section has the technical reference. It lists the field names you use in YAML, their types, and which ones are required. For how an automation is built in YAML, refer to Automations in YAML.

When this trigger starts an automation, it passes data about what happened to the automation. You can use this trigger data in the templates of your conditions and actions. To see which data is available, refer to Trigger data in templates.

In YAML, use trigger: webhook. A basic example looks like this:

trigger: webhook
webhook_id: "YOUR_WEBHOOK_ID"

This runs when Home Assistant receives a request to /api/webhook/YOUR_WEBHOOK_ID. By default, the webhook only accepts POST and PUT requests from your local network. To change this, use allowed_methods and local_only.

Options in YAML

This example uses a template for the webhook ID, based on a trigger variable:

trigger_variables:
  webhook_id_variable: "template_webhook_id"
triggers:
  - trigger: webhook
    webhook_id: "{{ webhook_id_variable }}"
    allowed_methods:
      - POST

Webhook security

A webhook doesn’t need a password or a token. Anyone who knows the webhook ID can send a request to it. To keep your webhooks secure:

• Don’t use webhooks for automations that are destructive, or that can create safety issues. For example, don’t use a webhook to unlock a lock or open a garage door.
• Treat a webhook ID like a password: use a unique value that’s hard to guess, and keep it secret.
• Don’t copy webhook IDs from public sources, including blueprints. Always create your own.
• Keep Only accessible from the local network (local_only) turned on if you don’t need access from the internet.

Good to know

• Home Assistant renders the webhook_id template once, when it sets up the trigger: when the automation loads, is reloaded, or is turned on. It doesn’t render the template again when a webhook call comes in, or when a state the template uses changes. In a Wait for a trigger step, Home Assistant renders the template each time the wait starts, and the template can use the variables of the run.
• Several triggers can use the same webhook ID, also in different automations. They all react to each request. Give them the same webhook settings, because Home Assistant uses the settings of the trigger that it sets up first.
• Requests through Home Assistant Cloud don’t count as local. This includes the Home Assistant Cloud webhook addresses and the remote access address of Home Assistant Cloud.
• Home Assistant almost always answers a webhook request with 200 OK, so that nobody can find out whether a webhook ID exists. It also answers 200 OK when the webhook ID doesn’t exist, or when a request from outside your local network reaches a webhook that only accepts local requests. Only a request method that isn’t allowed gets 405 Method Not Allowed. If a webhook doesn’t react, check the logs at Settings > System > Logs.
• A HEAD request always gets 200 OK, so that apps and services can check that the address exists. If HEAD isn’t one of the allowed methods, the trigger doesn’t react to it.

Try it yourself

Ready to test this? Go to Settings > Automations & scenes, create a new automation, and add this trigger. Save the automation, and then make the trigger react. For example, change the state of the targeted entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more], turn on a light that the trigger monitors, or change its brightness. To check whether the automation ran, open its traces.

For this trigger, send a request to the address of the webhook, as described in Sending a request to a webhook.

More examples

Real scenarios where this trigger fires in automations and scripts. Copy any example and adapt it to your setup. In the visual editor, select the UI options listed in the example when they are available, or paste the YAML code.

Automation: send a notification when a build fails

When your build server reports a failed build, send a notification to your phone. Set up the build server to send a POST request to the address of the webhook when a build fails.

• Trigger: Webhook
  • Webhook ID: The ID that Home Assistant generated
• Action: Send a notification message
  • Target: My Device (notify.my_device)
  • Message: The build failed.

alias: "Notify when a build fails"
triggers:
  - trigger: webhook
    webhook_id: "YOUR_WEBHOOK_ID"
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: "The build failed."

Automation: forward a message from the request

When the backup software on your NAS finishes a job, it can send a JSON request with a message, such as { "message": "Backup finished" }. This automation sends that message to your phone. Set up the backup software to send a POST request with a JSON body to the address of the webhook.

• Trigger: Webhook
  • Webhook ID: The ID that Home Assistant generated
• Action: Send a notification message
  • Target: My Device (notify.my_device)
  • Message: The message from the request ({{ trigger.json.message }})

alias: "Forward messages from the NAS"
triggers:
  - trigger: webhook
    webhook_id: "YOUR_WEBHOOK_ID"
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: "{{ trigger.json.message }}"

Still stuck?

To find out why the trigger didn’t react, make the change that it should react to, and then open the traces of the automation. If the automation didn’t run, there’s usually no trace, but some triggers record a Did not trigger trace. For details, refer to Testing automations. For common problems and their solutions, refer to Troubleshooting automations.

If that doesn’t help, the Home Assistant community is quick to help: join Discord for real-time chat, post on the community forum with the trigger you’re using and what you expected to happen, or share on our subreddit /r/homeassistant.

Related triggers

Explore related triggers:

• Manual event received: Triggers when an event is fired on the Home Assistant event bus.

• Template: Triggers when a template changes from false to true.