❮ Intégrations

Spécification du webhook

Entrixy envoie une commande Ouvrir à votre adresse et la signe. Voici le format de la requête et la vérification de la signature, pour que vous puissiez accepter la commande dans votre propre service, votre domotique ou sur votre carte.

Le webhook est le mode où l'ouverture n'est pas effectuée par notre contrôleur mais par votre propre système : Home Assistant, un relais sur le réseau local, votre propre serveur. Un objet Webhook a deux modes : application — le téléphone lui-même émet la requête HTTP vers votre adresse, en remplissant les valeurs dans le gabarit d'URL ; serveur — notre serveur envoie un POST signé, ce que décrit cette page. Récepteurs tout prêts : curl, Flask, Home Assistant, Node.js.

La requête

À l'ouverture, le serveur Entrixy envoie un POST vers votre webhook_url avec un corps JSON :

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

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

Champ	Valeur
`action`	`"open"` (pour les objets bistables également `"close"`)
`object_id`	l'identifiant de l'objet dans votre compte
`timestamp`	heure unix d'envoi, en secondes
`nonce`	16 caractères hexadécimaux (8 octets aléatoires), à usage unique
`signature`	HMAC-SHA256, voir plus bas

Les champs timestamp, nonce et signature n'arrivent que si l'objet possède un webhook_secret. Sans secret, le corps ne contient que {action, object_id}.

La signature

Ce qui est signé, c'est une chaîne canonique de quatre champs séparés par des points, et non le corps JSON lui-même : vous n'avez donc pas à reproduire notre sérialisation octet par octet :

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

webhook_secret se définit à la création de l'objet Webhook dans l'application. Les invités ne le reçoivent jamais — le serveur signe lui-même avec votre secret.

Comment la vérifier (de votre côté)

Construisez la même chaîne base = timestamp.nonce.action.object_id à partir des champs reçus.
Calculez HMAC-SHA256(webhook_secret, base) et comparez-le avec signature avec une comparaison à temps constant (hash_equals / hmac.compare_digest).
Anti-rejeu : rejetez la requête si |now − timestamp| > 300 secondes. Facultativement, conservez les derniers nonce valeurs et rejetez les répétitions.
La signature correspond et la requête est fraîche — exécutez l'ouverture.

Une adresse de webhook est généralement ouverte sans authentification, c'est pourquoi la vérification de la signature est obligatoire. Utilisez un secret d'au moins 16 caractères, ou mieux, générez-en un : openssl rand -hex 32.

Vecteur de test

Faites tourner votre vérification sur ces valeurs et contrôlez la signature :

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 réponse (facultative)

Répondez avec 200 OK. Pour que l'application affiche un résultat, renvoyez le JSON {"level":"success","message":"..."} (level: success/warning/danger/info). Sinon, un simple 200 suffit.

Récepteurs tout prêts

curl (envoi de test et vérification), Flask et Node.js (squelettes de service), Home Assistant (une automatisation webhook avec HMAC). Les relais sans prise en charge du HMAC (Shelly, Tasmota) se raccordent via un proxy ou Home Assistant.