Webhooks – Alarmierungsdaten extern weiterverarbeiten

Mit Webhooks kannst du Meldungen aus Pocsag Südtirol EO automatisch an ein externes System weiterleiten – zum Beispiel an eine eigene Automatisierung, eine Haussteuerung (z. B. ein Garagentor) oder ein Skript. Dieser Beitrag erklärt dir, wo du Webhooks findest, wie du sie einrichtest und was dabei zu beachten ist.

Wo finde ich die Webhook-Einstellungen?

Je nachdem, ob der Webhook für ein einzelnes Mitglied oder für ein ganzes Verwaltungskonto gelten soll, gehst du unterschiedlich vor:

Beim Mitglied (z. B. für ein Garagentor zuhause): Wechsle zum jeweiligen Mitglied und klicke auf der linken Seite auf das Webhook-Symbol.

Beim Verwaltungskonto (z. B. für ein Garagentor im Gerätehaus): Wechsle zum jeweiligen Verwaltungskonto und klicke oben in der Mitte auf das Webhook-Symbol.

Was ist ein Webhook?

Ein Webhook ist eine automatische Benachrichtigung, die beim Eintreten eines bestimmten Ereignisses (z. B. einer Alarmierung) an eine von dir festgelegte Internetadresse (URL) gesendet wird. Dadurch kann ein externes System sofort reagieren, ohne dass du selbst manuell etwas übertragen musst.

ℹ️ Hinweis: Die Einrichtung eines Webhooks ist derzeit ausschließlich über das Verwaltungskonto möglich.

Wie richte ich einen Webhook ein?

1. Webhook-URL eintragen

Trage im entsprechenden Feld die URL des Webhook-Endpunkts ein. An diese Adresse werden die Alarmmeldungen gesendet.

2. Authentifizierung einstellen

Für die Authentifizierung stehen dir drei Möglichkeiten zur Verfügung:

Keine Authentifizierung – Felder für Benutzername, Passwort und Token bleiben leer. Diese Option wird nicht empfohlen.
Basic Auth – Benutzername und Passwort eintragen. Beide werden als Base64-codiertes Paar (username:password) im HTTP-Header der Anfrage übermittelt.
Bearer Token – Benutzername und Passwort bleiben leer, stattdessen das Token eintragen. Es wird im HTTP-Header unter Authorization als Bearer <Token> übermittelt.

⚠️ Wichtig: Verzichte möglichst nicht auf eine Authentifizierung. Ohne Absicherung könnte grundsätzlich jede Person, die deine Webhook-URL kennt, Anfragen an dein Zielsystem senden.

3. Datentyp wählen

Wähle den Datentyp passend zu den Anforderungen deines Webhook-Empfängers:

json – für die Übertragung von JSON-Daten, z. B. {"id": 1, "name": "test1"}
form-data – für Daten im multipart/form-data-Format, häufig für Dateien und Formulare
x-www-form-urlencoded – für URL-kodierte Formulardaten

4. Zusätzliche Headers (optional)

Optional kannst du eigene HTTP-Header definieren. Diese müssen im JSON-Format angegeben werden, zum Beispiel:

[
  { "header_name": "X-Custom-Header 1", "header_value": "application/json" },
  { "header_name": "X-Custom-Header 2", "header_value": "custom_value" }
]

5. Standardinhalt mit zusätzlichem Inhalt kombinieren

Möchtest du den Standardinhalt (siehe Objektstruktur weiter unten) um eigene Daten erweitern, stelle die entsprechende Einstellung auf „Erweitern“.

6. Zusätzlicher Inhalt / Body (optional)

Optional kannst du zusätzlichen Inhalt im Body der HTTP-Anfrage angeben. Auch dieser muss im JSON-Format vorliegen, zum Beispiel:

{ "id": 1, "name": "test1" }

7. Webhook testen

Nachdem du den Webhook eingetragen hast, kannst du ihn über die Play-Taste direkt testen, um zu prüfen, ob die Verbindung funktioniert.

8. Webhook bei der Schleife aktivieren

Damit der Webhook bei einer Alarmierung tatsächlich aufgerufen wird, muss er zusätzlich bei der jeweiligen Schleife aktiviert werden:

Beim Mitglied: Öffne bei der jeweiligen Schleife die Schleifen-Details und aktiviere dort die Option Webhook.
Beim Verwaltungskonto (Organisation): Stelle bei der jeweiligen Schleife das Webhook-Symbol auf Grün.

⚠️ Wichtig: Ein eingerichteter Webhook wird erst dann tatsächlich ausgelöst, wenn er zusätzlich bei der entsprechenden Schleife aktiviert wurde. Ist die Aktivierung vergessen worden, bleibt der Webhook trotz korrekter Konfiguration inaktiv – das ist keine Fehlfunktion, sondern ein fehlender letzter Schritt.

Welche Daten werden bei einem Webhook übermittelt?

Das bei einer Alarmierung übermittelte Objekt enthält folgende Felder:

Feld	Beschreibung
bezirk	Name des Bezirks (Text)
organisation	Name der Organisation (Text)
schleife	Schleifennummer bzw. Bezeichnung (Text)
alarmstufe	Alarmstufe (Nummer, optional – kann „null“ sein)
stichwort	Hauptstichwort (Text, optional – kann „null“ sein)
unterstichwort	Unterstichwort (Text, optional – kann „null“ sein)
datum	Datum und Uhrzeit des Alarms (Text, Format: `yyyy-MM-ddTHH:mm:ss`)
typ	Typ der Nachricht („Alarm“ oder „Nachricht“)

Ein Beispiel für ein solches JSON-Objekt:

{
  "bezirk": "Bozen",
  "organisation": "Pocsag Südtirol",
  "schleife": "Sammelruf",
  "alarmstufe": 2,
  "stichwort": "Brand Mittel",
  "unterstichwort": "Gebäude",
  "datum": "2024-08-09T14:30:00",
  "typ": "Alarm"
}

Wofür kann ich Webhooks nutzen?

Webhooks eignen sich vor allem dann, wenn du Alarmierungsdaten automatisiert in einem anderen System weiterverarbeiten möchtest, zum Beispiel um:

ein Garagentor oder eine andere Haussteuerung bei einer Alarmierung automatisch zu öffnen
eine eigene Anzeige oder ein eigenes Dashboard mit Live-Daten zu befüllen
Meldungen an eine externe Software oder Schnittstelle weiterzuleiten
eigene Automatisierungen oder Benachrichtigungen zu bauen, die über die Standardfunktionen der App hinausgehen

Wichtiger Hinweis zu Support und Zuständigkeit

⚠️ Wichtig: Da Pocsag Südtirol als kostenloser Dienst angeboten wird, kann für die Einrichtung und Nutzung von Webhooks kein individueller Support geleistet werden. Zur Unterstützung stellen wir lediglich Log-Dateien zur Verfügung, mit denen sich Fehler selbstständig identifizieren und beheben lassen. Eine weiterführende technische Unterstützung oder detaillierte Fehleranalyse durch unser Team erfolgt nicht.

⚠️ Wichtig: Gemäß unseren AGB (Punkt 4.2) übernehmen wir keine Garantie für die einwandfreie Funktion des Webhook-Dienstes und haften nicht für Ausfälle, Fehlfunktionen oder daraus resultierende Schäden – einschließlich Einbruch oder Diebstahl, etwa bei einer webhook-gesteuerten Zugangs- oder Toröffnung.

Zusammenfassung

Webhooks lassen sich sowohl beim Mitglied als auch beim Verwaltungskonto einrichten – ausschließlich über das Verwaltungskonto.
Du konfigurierst URL, Authentifizierung (keine, Basic Auth oder Bearer Token), Datentyp (json, form-data oder x-www-form-urlencoded) sowie optionale Headers und Zusatzinhalte.
Über die Play-Taste kannst du den Webhook direkt testen.
Ein Webhook muss zusätzlich bei der jeweiligen Schleife aktiviert werden, damit er bei einer Alarmierung tatsächlich ausgelöst wird.
Das übermittelte Objekt enthält u. a. Bezirk, Organisation, Schleife, Alarmstufe, Stichwort, Unterstichwort, Datum und Typ der Meldung.
Für Webhooks wird kein individueller Support angeboten – lediglich Log-Dateien zur eigenständigen Fehlersuche. Gemäß AGB 4.2 wird keine Garantie für die einwandfreie Funktion übernommen.

Webhook erstellen