Home Assistant Guide

Simple tutorials for powerful automations

Beginner's Guide to Webhooks in Home Assistant

Webhooks are a powerful way for Home Assistant to interact with other systems, devices, or services on your network - or even across the internet. They let you trigger automations by making a simple web request (HTTP call) to your Home Assistant instance. This guide will explain what webhooks are, how to use them, and cover key tips for beginners.

What is a Webhook?

A webhook is a special URL (web address) that, when accessed (usually by sending some data to it), causes something to happen in Home Assistant. Think of it like a digital doorbell - when someone "rings" it (by making an HTTP request), Home Assistant responds by running an automation you set up.

  • The webhook URL is unique to each automation and includes a secret identifier.
  • Webhooks can receive data, allowing other systems to "talk" to Home Assistant.

How Webhook Triggers Work

In Home Assistant, you can set up an automation to be triggered by a webhook. When a web request is made to the special endpoint /api/webhook/<webhook_id>, Home Assistant will run the actions you specify in your automation. 

automation:
  triggers:
    - trigger: webhook
      webhook_id: "my_unique_webhook_id"
      allowed_methods:
        - POST
        - PUT
      local_only: true
# ... actions go here
  • webhook_id: A unique name you choose for this webhook (like a password - don't share it!).
  • allowed_methods: Which HTTP request types can trigger it (POST and PUT are common; GET and HEAD can be enabled if needed).
  • local_only: If true (the default), only devices on your local network or via Nabu Casa can trigger it. Set to false for access over the internet (not recommended for most users).

Triggering a Webhook

You trigger a webhook by sending an HTTP request to your Home Assistant URL plus the webhook endpoint. For example: 

curl -X POST -d 'key=value&key2=value2' https://your-home-assistant:8123/api/webhook/my_unique_webhook_id
  • POST and PUT are the most common request types.
  • If you want to use GET or HEAD requests, you must add them to allowed_methods in your trigger.
  • For remote access (from outside your network), you either need to use Nabu Casa Cloud or set local_only: false and open a port (be aware of the security risks).

Webhook Data and Templates

You can send data to a webhook in different formats:

  • Form data (default with most tools like curl -d): Accessible in your automation as trigger.data.
  • JSON data: To use JSON, set the Content-Type header to application/json. Accessible as trigger.json in automations.
  • URL query parameters: Data in the URL itself (like ?device=frontdoor) is available as trigger.query.

Example of a JSON payload: 

curl -X POST -H "Content-Type: application/json" -d '{ "action": "toggle" }' https://your-home-assistant:8123/api/webhook/my_unique_webhook_id

In your automation, you can access these values using templates, for example: 

{{ trigger.json.action }}

Security Tips for Webhooks

  • Keep your webhook_id secret! Anyone who knows it can trigger your automation. Use a unique, random string.
  • Do NOT use webhooks for dangerous actions (like unlocking doors, opening garage doors, disabling alarms, etc.).
  • Do not share webhook IDs publicly - never copy and paste someone else's webhook ID from a forum, and don't share yours.
  • Keep local_only enabled unless you absolutely need external access and understand the risks.
  • If you access your Home Assistant remotely, always use HTTPS to encrypt the connection.

Limitations and Testing

  • One webhook ID per automation: Each webhook ID can only be used in one automation trigger at a time.
  • Testing: You can test your webhook with tools like curl, Postman, or even simple scripts.
  • Debugging: Use the "Trace" feature in Home Assistant automations to see the data that was received by the webhook.

Common Use Cases for Webhooks

  • Connecting services like IFTTT, Zapier, or Tasker to Home Assistant (many third-party services can send webhook requests).
  • Triggering automations from custom scripts, Raspberry Pis, or other local devices.
  • Linking smart devices that can't directly integrate with Home Assistant.
  • Sending notifications to Home Assistant from external systems.