❮ Integrationen

Webhook-Spezifikation

Entrixy sendet einen Öffnen-Befehl an Ihre Adresse und signiert ihn. Hier stehen das Format der Anfrage und die Prüfung der Signatur, damit Sie den Befehl in Ihrem eigenen Dienst, Smart Home oder auf Ihrer Platine annehmen können.

Ein Webhook ist der Modus, in dem nicht unser Controller öffnet, sondern Ihr eigenes System: Home Assistant, ein Relais im lokalen Netz, Ihr eigener Server. Ein Webhook-Objekt kennt zwei Modi: App — das Telefon stellt die HTTP-Anfrage an Ihre Adresse selbst und setzt die Werte in die URL-Vorlage ein; Server — unser Server sendet ein signiertes POST, das diese Seite beschreibt. Fertige Empfänger: curl, Flask, Home Assistant, Node.js.

Die Anfrage

Beim Öffnen sendet der Entrixy-Server ein POST an Ihre webhook_url mit einem JSON-Body:

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

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

Feld	Wert
`action`	`"open"` (bei bistabilen Objekten auch `"close"`)
`object_id`	die Objekt-ID in Ihrem Konto
`timestamp`	Unix-Sendezeit in Sekunden
`nonce`	16 Hex-Zeichen (8 zufällige Bytes), einmalig
`signature`	HMAC-SHA256, siehe unten

Die Felder timestamp, nonce und signature kommen nur, wenn das Objekt ein webhook_secretbesitzt. Ohne Secret enthält der Body nur {action, object_id}.

Die Signatur

Signiert wird eine kanonische Zeichenkette aus vier durch Punkte getrennten Feldern, nicht der JSON-Body selbst — Sie müssen unsere Serialisierung also nicht Byte für Byte nachbauen:

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

webhook_secret wird beim Anlegen des Webhook-Objekts in der App festgelegt. Gäste erhalten es nie — der Server signiert selbst mit Ihrem Secret.

So prüfen Sie sie (auf Ihrer Seite)

Bauen Sie dieselbe Zeichenkette base = timestamp.nonce.action.object_id aus den empfangenen Feldern.
Berechnen Sie HMAC-SHA256(webhook_secret, base) und vergleichen Sie es mit signature mit einem zeitkonstanten Vergleich (hash_equals / hmac.compare_digest).
Replay-Schutz: weisen Sie die Anfrage zurück, wenn |now − timestamp| > 300 Sekunden beträgt. Optional können Sie die letzten nonce Werte speichern und Wiederholungen ablehnen.
Stimmt die Signatur und ist die Anfrage frisch — führen Sie die Öffnung aus.

Eine Webhook-Adresse ist meist ohne Authentifizierung offen, deshalb ist die Prüfung der Signatur zwingend. Verwenden Sie ein Secret mit mindestens 16 Zeichen, besser noch generieren Sie eines: openssl rand -hex 32.

Testvektor

Lassen Sie Ihre Prüfung über diese Werte laufen und kontrollieren Sie die Signatur:

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)

Die Antwort (optional)

Antworten Sie mit 200 OK. Damit die App ein Ergebnis anzeigt, geben Sie das JSON zurück {"level":"success","message":"..."} (level: success/warning/danger/info). Andernfalls genügt 200.

Fertige Empfänger

curl (Testversand und Prüfung), Flask und Node.js (Dienstgerüste), Home Assistant (eine Webhook-Automatisierung mit HMAC). Relais ohne HMAC-Unterstützung (Shelly, Tasmota) binden Sie über einen Proxy oder Home Assistant.