Webhooks desde reglas

Una regla puede llamar a una URL cuando se activa. Así su propio sistema conoce un evento de inmediato, por ejemplo una temperatura alta o la desconexión de un dispositivo.

Antes de empezar

• HAM Systems activa los webhooks por cuenta. Si la app muestra Los webhooks no están habilitados para su cuenta, contacte con soporte.
• Necesita una dirección https:// que acepte solicitudes POST desde internet.

Añadir un webhook a una regla

1. Abra el Menú. En el grupo Herramientas, toque Reglas en la nube.
2. Abra una regla o cree una regla nueva. Consulte crear una regla.
3. En las acciones, toque Añadir acción.
4. En la lista, seleccione Webhook.
5. En el campo URL, escriba la dirección de su sistema.
6. Si también quiere una llamada cuando la regla se restablece, toque Añadir acción de restablecimiento y seleccione Webhook de nuevo.
7. Toque Guardar.

Ordenador

Teléfono

Ordenador

Teléfono

Si la dirección no es correcta, la app muestra La URL no es válida.

La solicitud

La plataforma envía un POST con un cuerpo JSON (Content-Type: application/json):

{
  "event": "triggered",
  "rule": {
    "id": 4321,
    "name": "Fridge 1 temperature",
    "serialno": "e11:123",
    "this_data": [ { "...": "the rule conditions" } ]
  },
  "device_data": {
    "e11:123": {
      "R": { "T": 912, "GI": 1, "GIC": 0, "GI2": 1, "GI2C": 0 },
      "O": [],
      "S": { "...": "the device settings" }
    }
  },
  "messages": []
}

Campo	Contenido
event	triggered cuando la regla se activa. resolved cuando se ejecuta una acción Al restablecer.
rule.id, rule.name	El número y el nombre de la regla
rule.serialno	El dispositivo de la regla
rule.this_data	Las condiciones de la regla
device_data	El estado actual de cada dispositivo de la regla, con el número de serie como clave. El mismo formato que las actualizaciones del WebSocket.
messages	Errores, por ejemplo Failed to get state of e11:123 for rule #4321 cuando el estado de un dispositivo no está disponible

Los valores de R están sin procesar. En el ejemplo, T: 912 significa 9.12 °C. Consulte las definiciones en la API REST.

La plataforma quita de device_data los datos WiFi del dispositivo (nombre de la red, contraseña y datos empresariales).

Proteger el webhook

La solicitud no tiene firma (HMAC). Para comprobar que la solicitud viene de su regla:

1. Cree un secreto aleatorio largo, por ejemplo con openssl rand -hex 32.
2. Ponga el secreto en la cadena de consulta de la dirección: https://example.com/ham-hook?token=YOUR_SECRET.
3. En su sistema, rechace cada solicitud que no tenga el token correcto.

Precaución

Todas las personas que pueden ver la regla pueden ver también la dirección con el secreto. Si cambian las personas con acceso, cambie el secreto.

Reglas y límites

• La dirección debe empezar por https://.
• La plataforma no llama a direcciones locales y privadas: localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 100.64.0.0/10, 0.0.0.0/8 y las direcciones IPv6 relacionadas (::1, fe80:, fc00::/7).
• Hasta 5 llamadas cada 60 segundos por cada acción de webhook de una regla.
• Hasta 30 llamadas de webhook cada 60 segundos por cada cuenta.
• La plataforma omite las llamadas por encima de los límites. No las envía más tarde.
• La plataforma no comprueba el estado HTTP de su respuesta y no envía la solicitud de nuevo.
• Una acción puede tener un retardo (DESPUÉS). Una regla tiene hasta 12 acciones en total.

Prueba

Para una primera prueba, use un servicio público que muestre las solicitudes que recibe. Cree una regla con una condición fácil y mire el cuerpo de la solicitud.

Véase también

• Acciones de las reglas
• Datos en directo (WebSocket)
• Seguridad