UniFi Fob in Home Assistant nutzen – per Webhook zum Smart-Home-Schalter

Der UniFi-Fob ist so ein Gerät, das man einmal in die Hand nimmt und sofort weiß, wofür man es haben will. Ein Schlüsselanhänger, ein paar Tasten, Batterie drin, funkt direkt zum SuperLink-Gateway – kein WLAN, kein Zigbee-Stick, kein Pairing-Drama. In meinen Augen ist das der praktischste Smart-Home-Schalter im ganzen Haus: Er liegt am Schlüsselbund oder neben dem Bett, also genau da, wo man ihn braucht. Es gibt nur ein Problem – Home Assistant sieht ihn nicht. In diesem dritten und letzten Teil der Serie zeige ich dir, wie du die Tasten des Fobs trotzdem in Home Assistant nutzt: über einen Webhook aus dem Alarm Manager. Wenn du die ersten beiden Teile noch nicht kennst – in Teil 1 geht es um die Grundeinbindung von UniFi Protect, in Teil 2 um die SuperLink-Sensoren.

Das Problem: Home Assistant kennt die Tasten nicht

Fangen wir mit der unangenehmen Wahrheit an, damit du nicht eine Stunde lang nach Entitäten suchst, die es nicht gibt: Die Tasten der SuperLink-Geräte tauchen in Home Assistant nicht als Entitäten auf. Kein event-Entity, kein device_trigger, nichts – egal wie oft du die Integration neu lädst.

Der USL-Fob ist die batteriebetriebene Funk-Fernbedienung der SuperLink-Reihe und erscheint in Protect als Gerätetyp „Remote“. Dabei kann er eine Menge: In der Auswahl des Alarm Managers findest du pro Fob sechs Tasten – Arm Button, Night Mode Button, Disarm Button, Panic Button, Right Button und Left Button. Wer zusätzlich den Bewegungsmelder USL-Motion einsetzt, bekommt dort noch einen „Function Button“ dazu. Und jede dieser Tasten lässt sich nach Druckart unterscheiden: Press, Long Press (3s) und Double Press. Rechnerisch achtzehn unterscheidbare Auslöser an einem Schlüsselbund. Umso ärgerlicher, dass davon nichts in Home Assistant ankommt.

Ein Fehler deiner Installation ist das nicht. Im Home-Assistant-Repository gibt es dazu das Issue #171414 „Expose Superlink buttons“, erstellt am 20. Mai 2026, mit den Labels „integration: unifiprotect“ und „stale“. Es wurde als closed as not planned geschlossen, ein zugehöriger Pull Request existiert nicht. Der dort genannte offizielle Workaround ist sinngemäß genau das, was dieser Artikel beschreibt: Aktionen lassen sich per Webhook im Alarm Manager zuweisen, über die Trigger-Kategorie „Activity“ und den Punkt „Button“.

Jetzt kommt der Teil, bei dem im Netz gerne etwas durcheinandergerät, deshalb trenne ich das sauber. In der Python-Bibliothek uiprotect, die die Home-Assistant-Integration im Hintergrund benutzt, wurde am 26. Mai 2026 der Pull Request #864 „feat(api): add public API fobs endpoint group (list/get/update)“ gemerged (Merge durch RaHehl, Commit 514d87e). Der PR ergänzt ein Fob-Modell (Fob(ProtectModelWithId)), den Enum-Wert ModelType.FOB sowie die Endpunkte GET /v1/fobs, GET /v1/fobs/{id} und PATCH /v1/fobs/{id}.

Das klingt nach der Lösung – ist es aber nicht, und das muss man ehrlich sagen: Damit lassen sich Fobs auflisten, abrufen und umbenennen. Es ist reine Verwaltung. Tastendruck-Ereignisse liefert diese API nicht. Der PR ist die Grundlage dafür, dass Fobs über die öffentliche API überhaupt bekannt sind – er macht die Buttons aber nicht automatisierbar. Wer heute auf einen Tastendruck reagieren will, kommt am Webhook-Weg nicht vorbei.

Die Lösung: Webhook aus dem Alarm Manager

Das Prinzip ist erfreulich simpel. Du legst in UniFi Protect einen Alarm an, der auf einen bestimmten Tastendruck reagiert. Als Aktion bekommt dieser Alarm keinen Push und keine Sirene, sondern einen HTTP-Aufruf an einen Webhook von Home Assistant, an dem eine Automation hängt.

Protect ruft also an, Home Assistant hebt ab und macht das Licht an. Mehr passiert nicht – und genau deshalb ist es so robust. Wir bauen von hinten nach vorne: erst die Automation, dann der Alarm. Denn du brauchst die Webhook-URL, bevor du sie in Protect eintragen kannst.

Schritt 1: Webhook-Automation in Home Assistant anlegen

Geh in Home Assistant auf Einstellungen → Automationen & Szenen → Automation erstellen und wähle als Auslöser „Webhook“. Home Assistant schlägt dir eine zufällige Webhook-ID vor. Die kannst du übernehmen oder durch eine eigene ersetzen – sie ist frei wählbar. Aus der ID ergibt sich die Ziel-URL nach diesem Muster:

http://<HA-Adresse>:8123/api/webhook/<webhook-id>

Bei mir also http://192.168.1.50:8123/api/webhook/usl-fob-arm. Wichtig: Der Webhook-Trigger braucht kein Zugriffstoken – kein Passwort, keinen Long-Lived-Token. Die zufällige ID ist das Geheimnis.

Behandle die Webhook-URL wie ein Passwort. Wer sie kennt, kann die Automation auslösen. Nimm eine lange, zufällige ID – am besten die, die Home Assistant selbst vorschlägt – und schreib sie nicht in ein öffentliches Forum oder einen Screenshot. Standardmäßig sind Webhooks in Home Assistant nur aus dem lokalen Netz erreichbar. Für unseren Fall ist das genau richtig, weil Protect-Konsole und Home Assistant ohnehin im selben Netz stehen. Wie du dein Netz sauber aufteilst, habe ich im Beitrag zum Heimnetzwerk einrichten beschrieben.

In YAML sieht so eine Automation minimal aus:

alias: Fob Arm-Taste
triggers:
  - trigger: webhook
    webhook_id: usl-fob-arm
    allowed_methods: [POST]
    local_only: true
actions:
  - action: light.turn_off
    target:
      entity_id: all
mode: single

Zum Debuggen empfehle ich dir aber, als Aktion erst einmal etwas Harmloses und gut Sichtbares zu nehmen – eine dauerhafte Benachrichtigung:

actions:
  - action: persistent_notification.create
    data:
      title: Fob
      message: "Webhook usl-fob-arm ausgelöst"

So siehst du sofort, ob der Aufruf angekommen ist, ohne dass gleich das halbe Haus dunkel wird. Bei Grundlagen hilft dir der Beitrag zum Home Assistant einrichten weiter.

Schritt 2: Alarm in UniFi Protect anlegen

Jetzt die andere Seite:

1. Öffne den Alarm Manager. Der hat einen eigenen Punkt im Hauptmenü der linken Seitenleiste.
2. Klick auf „Create Alarm“.
3. Wähle bei den Triggern die Kategorie „Activity“.
4. Setz dort das Häkchen bei „Button“.
5. Wähle den Press Type – also Press, Long Press (3s) oder Double Press.
6. Im Bereich „Scope“ wählst du die gewünschten Tasten aus. Die Liste ist nach Gerät gruppiert, du findest also deinen „USL Fob“ mit seinen sechs Tasten als Block.
7. Rechts unter „Action“ wählst du den Punkt „Webhook“.

Im Webhook-Bereich erwartet dich zuerst ein Dropdown mit drei Typen: Slack, ServiceNow und Custom Webhook. Für Home Assistant ist „Custom Webhook“ der richtige Eintrag – die beiden anderen bauen fertige Nachrichten für ihre jeweiligen Dienste.

Danach erscheinen die eigentlichen Felder: Delivery URL (hier kommt deine Webhook-Adresse rein), Delivery method mit der Auswahl GET oder POST – Standard ist POST, und dabei kannst du bleiben –, ein Dropdown Authentication mit dem Standard „None“, ein Link „Add Header“ für eigene Header, die Auswahl zwischen Default Content und Custom Content, eine Option Use Thumbnails sowie ein Link „Test Alarm“, der einen Testaufruf auslöst.

Für unseren Zweck reicht: Custom Webhook, URL eintragen, POST, Authentication auf None, Default Content. Home Assistant interessiert sich bei diesem Aufbau ohnehin nicht für den Inhalt – dazu gleich mehr.

Schritt 3: Testen

Halt dich an diese Reihenfolge, dann findest du Fehler in Sekunden statt in Stunden:

1. Automation in Home Assistant speichern. Ein Webhook, dessen Automation nur im Editor steht, existiert nicht.
2. In Protect auf „Test Alarm“ klicken. Das ist der große Vorteil: Du musst nicht durchs Haus laufen und Tasten drücken. Protect löst den Webhook direkt aus.
3. In Home Assistant nachsehen. Wenn du die persistente Benachrichtigung eingebaut hast, poppt sie jetzt auf. Alternativ siehst du eingehende Aufrufe unter Einstellungen → Automationen & Szenen an der Spalte „Zuletzt ausgelöst“ und detaillierter im Protokoll.
4. Erst dann den echten Tastendruck ausprobieren. Wenn der Test durchgeht und die Taste nicht, liegt es am Scope oder am Press Type – nicht an der URL.

Kommt beim Testaufruf nichts an, sind die üblichen Verdächtigen: falsche IP oder falscher Port in der Delivery URL, ein Tippfehler in der Webhook-ID, oder getrennte VLANs ohne Freigabe.

Eine Taste, ein Webhook — warum das der saubere Weg ist

Jetzt die Designentscheidung, die den Unterschied zwischen „läuft“ und „nervt“ ausmacht. Protect schickt pro Alarm eine feste Nutzlast. Packst du mehrere Tasten in einen Alarm, steht darin nicht sauber auswertbar, welche gedrückt wurde.

Der saubere Weg ist deshalb: pro Taste ein eigener Alarm mit eigener Webhook-ID. Also zum Beispiel .../api/webhook/usl-fob-arm, .../api/webhook/usl-fob-disarm, .../api/webhook/usl-fob-night und so weiter. In Home Assistant hast du dann pro Taste eine eigene Automation, die genau eine Sache tut. Keine Templates, keine Payload-Auswertung, keine Rätsel.

Die Alternative wäre eine gemeinsame Webhook-ID für alle Tasten plus eine Vorlage in Home Assistant, die aus dem Payload herausliest, welche Taste es war. Das geht – ist aber aufwendiger, fehleranfälliger und bricht dir bei der nächsten Protect-Aktualisierung möglicherweise weg. Ich rate davon ab: Sechs kleine Alarme sind schnell geklickt und in einem halben Jahr noch verständlich. Anregungen zur Darstellung findest du im Beitrag zum Home-Assistant-Dashboard.

Was du damit bauen kannst

Alles-Aus beim Verlassen des Hauses (Arm). Ein Druck, und Licht, Steckdosen und Multimedia gehen aus, die Heizung fällt auf Absenktemperatur. Der Klassiker – und der Grund für den Fob am Schlüsselbund: Man greift beim Rausgehen ohnehin zum Schlüssel.

Nachtmodus (Night Mode). Der Fob liegt bei mir neben dem Bett. Ein Druck schaltet das Erdgeschoss dunkel, dimmt den Flur auf zehn Prozent Orientierungslicht und senkt die Heizung. Morgens macht die Disarm-Taste den Weg zurück.

Panik-Taste. Alle Lichter im Haus auf volle Helligkeit und eine Push-Benachrichtigung aufs Handy – nachts bei einem verdächtigen Geräusch ziemlich beruhigend. Ehrlich dazugesagt: Das ersetzt keinen Notruf und keine Alarmanlage mit Aufschaltung. Es macht Licht und schickt eine Nachricht, mehr nicht.

Links und Rechts frei belegen. Die Richtungstasten haben keine feste Bedeutung – ideal für Rollläden hoch und runter oder zwei Lieblingsszenen. Mit Long Press und Double Press sind es pro Taste sogar drei Funktionen.

Grenzen

Damit du weißt, worauf du dich einlässt – der Webhook-Weg funktioniert zuverlässig, aber er hat klare Grenzen:

• Einbahnstraße. Protect ruft an, Home Assistant hört zu. Zurück fließt nichts. Du bekommst über diesen Weg also keinen Status und auch keine Batterieanzeige des Fobs in Home Assistant.
• Protect muss laufen. Der Fob funkt zum Gateway, das Gateway hängt an der Konsole, und die Konsole schickt den Webhook. Steht Protect, steht auch deine Taste.
• Latenz. Zwischen Druck und Reaktion liegt spürbar mehr als bei einem direkt in Home Assistant eingebundenen Zigbee-Taster. Im Alltag ist das meist unkritisch, aber es ist da.
• Kein Wiederholversuch. Wenn der Aufruf wegen eines Netzwerkproblems oder eines gerade neu startenden Home Assistant nicht ankommt, ist das Ereignis weg. Es wird nicht nachgeliefert.
• Updates. Bei einem Protect-Update können sich Payloads oder Feldnamen ändern. Genau deshalb die Empfehlung, sich nicht auf den Payload zu verlassen.

Fazit

Damit ist die kleine Serie rund. In Teil 1 haben wir UniFi Protect grundsätzlich an Home Assistant angebunden, in Teil 2 die SuperLink-Sensoren nutzbar gemacht, und in diesem Teil den Fob – notgedrungen über den Umweg Webhook, dafür aber stabil und ohne Bastelei an der Integration selbst.

Schade bleibt es trotzdem: Die Hardware kann alles, die Bibliothek kennt die Fobs inzwischen, und die Tastendrücke landen trotzdem nicht als Ereignisse in Home Assistant. Eine native Unterstützung wäre wünschenswert – bis dahin ist ein Custom Webhook pro Taste der Weg, der heute funktioniert. Zehn Minuten Einrichtung, und der praktischste Schalter im Haus tut endlich, was er soll.

Häufige Fragen

Warum sehe ich meinen Fob nicht in Home Assistant?

Weil die Integration die Tasten der SuperLink-Geräte nicht als Entitäten anlegt. Das ist kein Fehler bei dir, sondern der aktuelle Stand – das entsprechende Issue im Home-Assistant-Repository wurde als „not planned“ geschlossen. Der Webhook aus dem Alarm Manager ist der offiziell genannte Workaround.

Brauche ich ein Zugriffstoken für den Webhook?

Nein. Der Webhook-Trigger in Home Assistant kommt ohne Token und ohne Anmeldung aus – die zufällige Webhook-ID ist das Geheimnis. Genau deshalb solltest du eine lange, zufällige ID verwenden und die URL wie ein Passwort behandeln. In Protect kannst du „Authentication“ auf None lassen.

Kann ich mehrere Tasten auf einen Webhook legen?

Technisch ja, du kannst im Scope mehrere Tasten anhaken. Dann weißt du in Home Assistant aber nicht mehr zuverlässig, welche es war, ohne den Payload auszuwerten. Empfehlenswerter ist ein eigener Alarm mit eigener Webhook-ID pro Taste.

Funktioniert das von unterwegs?

Für den beschriebenen Aufbau ist das nicht nötig – Protect-Konsole und Home Assistant stehen im selben Netz, und Webhooks sind standardmäßig auf lokale Aufrufe beschränkt. Diese Einschränkung aufzuheben, um von außen zu triggern, würde ich nicht empfehlen: Eine ungeschützte URL im Internet ist genau das, wonach es klingt.

Was passiert, wenn Home Assistant gerade neu startet?

Dann geht der Tastendruck verloren. Protect schickt den Aufruf ab, findet niemanden und versucht es nicht noch einmal. Bei einem Update oder Neustart also kurz warten und die Taste danach erneut drücken.