En esta entrada incorporamos otra utilidad poderosa a nuestra caja de herramientas, bienvenido al mundo de los webhooks!
¿Qué es un webhook?
Un webhook es una forma de enviar información automáticamente a una aplicación cuando ocurre un evento determinado, sin que la segunda tenga que preguntar constantemente si algo ha cambiado (en contraposición, por ejemplo, a la integración de una API).
Esta comunicación unidireccional se basa en el protocolo HTTP («Hypertext Transfer Protocol»), mediante el que se envía un comando ‘POST’ a una URL determinada por ti. El ‘webhook’ o mensaje se envía de forma inmediata cuando ocurre el evento que lo genera, y suele llevar un ‘payload’ en formato JSON con información sobre el evento (es decir, el contenido del mensaje).
¿Qué tiene que ver con Home Assistant?
En muchas ocasiones hemos hablado de qué sucede cuando quieres llevar información a Home Assistant desde una fuente externa, pero no existe la integración que estás buscando. En estos casos siempre podemos recurrir a métodos alternativos (como, por ejemplo, usar Tasker o los ‘intents’ de Android), y los webhooks es uno de ellos.
De hecho ya te he explicado anteriormente como puedes utilizar herramientas con una interfaz gráfica muy sencilla (como Make o n8n), para conectar servicios de terceros con Home Assistant mediante el envío de webhooks.
Además de importar información a HA, también puedes ejecutar acciones sin acceder directamente a tu instancia usando webhooks. Esto puede ser muy útil, por ejemplo, cuando quieres dar la posibilidad a alguien externo para hacer ciertas cosas, sin darle acceso a tu instalación.
Webhooks en Home Assistant
Requisitos previos
Antes de nada, si has entendido el concepto, puedes deducir que hay un requisito indispensable para poder utilizar webhooks en Home Assistant. Necesitas tener acceso desde el exterior, de forma que dispongas de un dominio o URL pública accesible a la que puedas enviar los comandos.
Esto no sería necesario si las llamadas las vas a realizar desde algún dispositivo conectado a tu red local (puesto que la URL sería la IP de Home Assistant), aunque personalmente no veo muchas aplicaciones de uso en este caso.
Ejecutar acciones mediante webhooks
Digamos que quieres ejecutar una acción (por ejemplo, encender una luz) y quieres que el webhook sea el desencadenante o ‘trigger’. Puedes imaginar que este webhook es un botón, y que cuando lo pulses (ejecutes) se encenderá la luz. En este caso es muy sencillo de hacer, ya que como únicamente necesitas reproducir esa «pulsación», puedes hacerlo llamando a esa URL incluso desde tu propio navegador, o al escanear un QR.
Los pasos para configurar tu webhook serían los siguientes:
- En Home Assistant, ve a Configuración > Automatizaciones y escenas > Crear automatización.
- Pulsa en «Añadir disparador» y busca «Webhook», y verás que automáticamente genera un identificador para este webhook. Para ilustrar el ejemplo, voy a renombrarlo a ‘WebhookTrigger’.
- Observa que a la derecha te aparece el icono de un engranaje. Si pulsas sobre él puedes seleccionar los métodos permitidos en el uso de este webhook. Si únicamente quieres ejecutar una acción, bastaría con que marcases el método «GET».
- A continuación añade la acción que quieras ejecutar al final de automatización (por ejemplo, alternar el encendido y apagado de una luz).
- Ya ves que, en realidad, crear la automatización es algo muy sencillo de hacer. El código del ejemplo sería el siguiente:
alias: Ejemplo Webhook
description: ""
triggers:
- trigger: webhook
allowed_methods:
- GET
local_only: false
webhook_id: WebhookTrigger
conditions: []
actions:
- action: light.toggle
metadata: {}
data: {}
target:
entity_id: light.escritorio
mode: single
- Bien, lo siguiente que necesitar es conocer la URL que has creado para ejecutar tu webhook, que tiene la siguiente estructura:
- URL accesible. Este es el dominio mediante el que accedes a Home Assistant desde el exterior (por ejemplo, «https://aguacatec.es/%22.
- Ruta. A continuación del dominio debes incluir la ruta que indica que vas a ejecutar un webhook («api/webhook/»).
- Identificador del webhook. Por último, el identificador del webhook que quieres ejecutar (por ejemplo, «WebhookTrigger»)
- Al final te quedaría algo así:
- Si copias esta URL en tu navegador y accedes a ella, comprobarás que se ejecuta la acción correspondiente. Obviamente, este no me parece el método más interesante, pero puedes incluir esta URL en QR o una etiqueta NFC, o incluso ejecutar acciones desde una web externa.
Enviar información mediante webhooks
Frecuentemente lo más interesante que podemos hacer con los webhooks es enviar información enriquecida. También hay muchas acciones que requieren que facilitemos algún parámetro (por ejemplo, el porcentaje de brillo de una luz o la temperatura del termostato).
Como te indicaba al principio del artículo, esta información se denomina ‘payload’ (puede ser un mensaje, un estado, un número o cualquier dato estructurado) y generalmente se encuentra en formato JSON. En este caso, no puedes hacerlo directamente desde el navegador, pero es igualmente sencillo.
Los pasos para configurar tu webhook serían los siguientes:
- En Home Assistant, ve a Configuración > Automatizaciones y escenas > Crear automatización.
- Pulsa en «Añadir disparador» y busca «Webhook», y verás que automáticamente genera un identificador para este webhook. Para ilustrar el ejemplo, voy a renombrarlo a ‘WebhookTriggerPayload’.
- Pulsa sobre el icono del engranaje a la derecha, y verifica que está marcado el método ‘POST’ (necesario para enviar información enriquecida).
- A continuación añade la acción que quieras ejecutar al final de automatización (por ejemplo, encender una luz con un porcentaje de brillo proporcionado por el webhook). Ten en cuenta que para ello tienes que utilizar ‘templates’ en la definición de tus acciones.
- El código del ejemplo sería el siguiente:
alias: Ejemplo Webhook
description: ""
triggers:
- trigger: webhook
allowed_methods:
- POST
local_only: false
webhook_id: WebhookTriggerPayload
conditions: []
actions:
- action: light.turn_on
metadata: {}
data:
brightness_pct: "{{ trigger.json.brightness|int }}"
target:
entity_id: light.escritorio
mode: single
- La URL de tu webhook se construiría exactamente de la misma forma que en el paso anterior (‘https://aguacatec.es/api/webhook/WebhookTriggerPayload’. La diferencia es que ahora tenemos que incluir en esta llamada la información enriquecida (siguiendo el ejemplo, sería el brillo de la luz). En este caso el payload, para fijar un nivel de brillo del 80%, tendría el siguiente aspecto:
{{"brightness": 80}}
- Por último, la mejor forma de realizar esta llamada incluyendo la información va a depender del caso de uso. Si quieres utilizar herramientas como Make o n8n, encontrarás ejemplos en la entrada correspondiente. No obstante, en realidad puedes hacerlo creando un sencillo archivo html que contenga un pequeño script.
- Si quieres hacer la prueba, crear un fichero ‘.txt’ en tu ordenador, pega y adapta el siguiente código con los pasos anteriores, y después renombra la extensión del fichero a ‘.html’.
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Webhook con Payload</title>
</head>
<body>
<h2>Webhook a Home Assistant</h2>
<button onclick="enviarWebhook()">Enviar webhook</button>
<script>
function enviarWebhook() {
fetch("https://aguacatec.es/api/webhook/WebhookTriggerPayload", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
brightness: 80
})
})
.then(response => {
if (response.ok) {
alert("✅ Webhook enviado con éxito.");
} else {
alert("❌ Error al enviar el webhook.");
}
})
.catch(error => {
alert("⚠️ Error de red: " + error);
});
}
</script>
</body>
</html>
- De esta forma habrás creado una pequeña interfaz web con el siguiente aspecto. Si pulsas sobre el botón, de nuevo, comprobarás que la acción se ejecuta teniendo en cuenta la información enviada.
- A partir de aquí, como siempre, el límite está en tu imaginación!
