Hintergrund

Mit den generischen Webhooks können beliebige HTTP Aufrufe durchgeführt werden. Zur Verfügung steht das HTTP Verb GET. Als Query Parameter stehen das Stichwort und der Einheitenname zur Verfügung. Das genaue Format kann direkt bei der Konfiguration als Vorschau dargestellt werden.

Ab aPager PRO iOS Version 1.22.0 steht auch das HTTP Verb POST zur Verfügung.

Die Webhooks werden nur ausgelöst, wenn es sich um einen “echten” Alarm (Reiter “Alarm”) handelt. Info-, Wetter- oder Statusalarme werden nicht berücksichtigt!

Anforderungen an die URL

URLs müssen generell als https:// vorliegen, also eine TLS-Verschlüsselung vorweisen. Das Format http:// wird bei iOS nicht unterstützt und vom System blockiert.

Konfiguration in aPager PRO

Navigieren Sie zu Einstellungen → “Smart Home” → “Webhooks”

Wählen Sie einen beliebigen Webhook 1-5 durch seitliches Scrollen.

Tragen Sie die URL ein und wählen Sie, ob die Einheitenkennung und/oder das Stichwort ebenfalls übertragen werden sollen.

Durch Testen können Sie die generierte URL sehen.

Nach erfolgreichem Test speichern Sie den Webhook bitte.

Zum Testen kann diese Seite verwendet werden:

Webhook.site - Test, transform and automate Web requests and emails

Natürlich benötigen Sie für den Produktivbetrieb die korrekte URL Ihres Anbieters.

Experteneinstellungen

Hier können Sie wählen wie die Einheitenkennung und das Stichwort übertragen werden sollen. Die Query Parameter lauten im Normalfall “unit” und “keyword”. Sie können diese beliebig anpassen und durch “Testen” eine Vorschau der generierten URL sehen.

Nur im Test werden “unit1” und “B3” als Werte für die Query Parameter verwendet. Bei einem echten Einsatz werden diese mit den konkreten Werten des aktuellen Alarms ersetzt.

Wie im übergeordneten Artikel beschrieben, können Sie den konfigurierten Webhook nun unter “Einheitenkonfiguration” → “Klingeltöne” an der gewünschten Einheit hinterlegen.

Fertig, ihr erster Webhook ist nun verknüpft. Testen Sie die Auslösung am besten gleich mit einem Testalarm an die konfigurierte Einheit direkt aus FE2.

Experteneinstellung: Platzhalter in URL verwenden

1.15.0+

Es ist möglich Platzhalter innerhalb der URL zu verwenden, die zur Laufzeit durch die konkreten Werte ersetzt werden. Hierfür müssen die Schalter für Einheitenkennung / Stichwort übertragen aktiv sein.

Die unterstützten Parameter sind:

Parameter	Ersetzung durch

Parameter	Ersetzung durch
{unit}	Einheitenkennung
{keyword}	Stichwort

Dadurch ergeben sich Möglichkeiten URLs wie die nachfolgende zu erstellen:

Eintrag in das Feld URL: https://mywebhookservice.com?cmd=set-{keyword}-on

Zur Laufzeit wird daraus: https://mywebhookservice.com?cmd=set-B3-on

Experteneinstellung: HTTP POST statt GET verwenden

1.22.0+

Nach Aufklappen der Experteneinstellungen kann der Schalter HTTP POST statt GET aktiviert werden.

Webhooks werden dann als HTTP POST übertragen.

Bei gibt es folgende Besonderheiten:

Es werden keine Query-Parameter an die URL angehängt (dynamisch auf Basis von Einheit & Stichwort; händisch der URL hinzugefügte Parameter sind möglich)
Es wird eine JSON Payload generiert mit den festen Keys “unit” und “keyword”, siehe Screenshot (rote Umrandung)
URL-Platzhalter sind ohne zusätzliche Aktivierung nutzbar
- https://meinewebhookurl.de/{unit}/xyz?param={keyword} wäre also eine gültige Kombination, die zur Laufzeit bspw. zu https://meinewebhookurl.de/unit1/xyz?param=B3 auflösen würde

Auch hier empfehlen wir die Seite Webhook.site für Tests vor der Live-Integration in bestehende Smart Home Systeme.

Experteneinstellung: Eigenen Header-Wert übertragen

6.1.x

Es ist möglich eigene Header-Werte zu übertragen, z.B. um einen API-Key zu setzen.

Bitte aktivieren Sie “Eigenen Header-Wert übertragen” und tragen die gewünschten Daten ein. Testen Sie die eingestellten Werte bitte anschließend über “Testen”

Handbuch

Allgemeine Webhooks iOS