❮ Integraciones

Especificación del webhook

Entrixy envía una orden de Abrir a tu dirección y la firma. Aquí tienes el formato de la petición y cómo verificar la firma, para que puedas aceptar la orden en tu propio servicio, casa inteligente o placa.

El webhook es el modo en el que la apertura no la ejecuta nuestro controlador, sino tu propio sistema: Home Assistant, un relé de la red local, tu propio servidor. Un objeto de tipo Webhook tiene dos modos: aplicación — el propio teléfono hace la petición HTTP a tu dirección, rellenando los valores en la plantilla de la URL; servidor — nuestro servidor envía un POST firmado, que es lo que describe esta página. Receptores ya hechos: curl, Flask, Home Assistant, Node.js.

La petición

Al abrir, el servidor de Entrixy envía un POST a tu webhook_url con un cuerpo JSON:

POST <your webhook_url>
Content-Type: application/json

{
  "action":    "open",
  "object_id": 42,
  "timestamp": 1750000000,
  "nonce":     "0011223344556677",
  "signature": "9d7b58066094fa88..."
}

Campo	Valor
`action`	`"open"` (para objetos biestables también `"close"`)
`object_id`	el id del objeto en tu cuenta
`timestamp`	hora unix de envío, en segundos
`nonce`	16 caracteres hex (8 bytes aleatorios), de un solo uso
`signature`	HMAC-SHA256, ver más abajo

Los campos timestamp, nonce y signature solo llegan si el objeto tiene un webhook_secret. Sin secreto, el cuerpo lleva solo {action, object_id}.

La firma

Lo que se firma es una cadena canónica de cuatro campos separados por puntos, no el cuerpo JSON en sí, así que no tienes que reproducir nuestra serialización byte a byte:

base = "<timestamp>.<nonce>.<action>.<object_id>"
signature = HMAC-SHA256(webhook_secret, base)   // hex

webhook_secret se define al crear el objeto Webhook en la aplicación. Los invitados no lo reciben nunca: el servidor firma él mismo con tu secreto.

Cómo verificarla (en tu lado)

Construye la misma cadena base = timestamp.nonce.action.object_id a partir de los campos recibidos.
Calcula HMAC-SHA256(webhook_secret, base) y compáralo con signature con una comparación de tiempo constante (hash_equals / hmac.compare_digest).
Antirrepetición: rechaza la petición si |now − timestamp| > 300 segundos. Opcionalmente, guarda los últimos nonce valores y rechaza las repeticiones.
Si la firma cuadra y la petición es reciente, ejecuta la apertura.

Una dirección de webhook suele estar abierta sin autenticación, así que verificar la firma es obligatorio. Usa un secreto de al menos 16 caracteres, o mejor aún, genéralo: openssl rand -hex 32.

Vector de prueba

Pasa tu verificación por estos valores y comprueba la firma:

webhook_secret = webhook_secret_example_key
timestamp      = 1750000000
nonce          = 0011223344556677
action         = open
object_id      = 42

base       = 1750000000.0011223344556677.open.42
signature  = 9d7b58066094fa88acc0afa7aa805fc5f0d008d33cb11b8aa2366102da8e20f1
  = HMAC-SHA256(webhook_secret, base)

La respuesta (opcional)

Responde con 200 OK. Para que la aplicación muestre un resultado, devuelve el JSON {"level":"success","message":"..."} (level: success/warning/danger/info). Si no, basta con 200.

Receptores ya hechos

curl (envío de prueba y verificación), Flask y Node.js (esqueletos de servicio), Home Assistant (una automatización de webhook con HMAC). Los relés sin soporte de HMAC (Shelly, Tasmota) se conectan a través de un proxy o Home Assistant.