Triggers and automations

Triggers and automations

Defining triggers

As an user with administrator privilege you will find Triggers in the Admin menu. This is where you define the triggers which users can use.

Triggers

Initially this will just be an empty space. But once you add triggers, you'll see a list of these here. You can either modify or delete existing triggers.

Add / modify trigger

This section either allows you to create a new trigger, or it will be populated with the data of an existing trigger if you choose to edit a trigger.

Caption

The text of the button the users will see in their trigger list.

Order

A numeric value by which the trigger list will be sorted. The order is ascending.

Trigger data

The payload that will be included when the webhook is called. The format is raw JSON.
Example:

{
"service": "light.turn_on",
"entity_id": "light.kitchen"
}

Whitespace will be stripped out when saving the trigger. So you can use it while constructing the payload, but if you edit it later on it will be gone.
The border of the textarea in which you construct the payload will change to the color red if the content is not valid JSON.

Webhook URI

This is the full URI to which the webhook request will be sent. It will depend on your setup. This section of the Home Assistant documentation covers webhook triggers.

Password

You may want to restrict access to triggers to a subset of the available users. As of today trigger availability is global. As a workaround you can specify a simple password / pin which a user will be prompted for when pushing the trigger button. It's basically another, trigger-specific, authentication layer.
This is just used internally and will not be stored encrypted. Do not use secret passwords that are used elsewhere!

Include user

When this checkbox is checked, the trigger data will be extended with the user information of the user that executed the trigger. This can be used to fine tune the automation by using the username as a condition.

Automation in Home Assistant

This is a minimal automation in Home Assistant (YAML style) that will write a message to the logs at the warning level. It includes the trigger data, allowing you to observe what data arrives at Home Assistant after executing the trigger.

automation old:
  trigger:
    platform: webhook
    webhook_id: secretwebhookid
  action:
    service: system_log.write
    data_template:
      message: "{{ trigger.json }}"
      level: warning

If you add a trigger with the trigger data {"test": "foo"} and check the Include user checkbox, the output will look something like this:

2020-01-17 22:22:37 WARNING (MainThread) [homeassistant.components.system_log.external] {'test': 'foo', 'user': 'john.doe'}

And here a more complex automation with the user as a condition and multiple actions.

- alias: Unlock the door
  description: Unlocking the door via HASS-WH-Triggers
  trigger:
  - platform: webhook
    webhook_id: secretwebhookid
  condition:
  - condition: template
    value_template: '{{ trigger.json.user in ["bob", "alice"] }}'
  action:
  - service: lock.unlock
    data:
      entity_id: lock.mylock
  - service: switch.turn_on
    data:
      entity_id: switch.myswitch
  - service: system_log.write
    data_template:
      message: "{{ trigger.json.user }} has unlocked the door"
      level: warning