Webhook-Schnittstelle
Positionen, Status und Alarmeingänge per HTTP empfangen, Nachrichten mit Einsatzdaten verschicken – alle Felder und Beispiele.
Die Anbindung vom Typ Webhook (generisch) verbindet Lagewerk mit Systemen, die HTTP sprechen:
- Empfangen: Fremdsysteme schicken Fahrzeugpositionen, Fahrzeugstatus und Alarmeingänge
(Einsatz-Kandidaten mit Anhängen) per
POSTan Lagewerk. - Senden: Technische Aufgaben schicken mit der Funktion Nachricht Einsatzdaten per
POSTan ein Fremdsystem.
Jede Webhook-Anbindung hat ihr eigenes Empfangs-Token und ihre eigenen Freigaben. Für verschiedene Absender oder verschiedene Rechte legen Sie mehrere Webhook-Anbindungen an.
Einrichten
Unter Verwaltung → Anbindungen eine Anbindung vom Typ Webhook (generisch) anlegen. Dafür brauchen Sie das Recht Anbindungen verwalten.
| Feld | Bedeutung |
|---|---|
| Name | Anzeigename, erscheint auch als Absender im Einsatztagebuch („anbindung:Name“). |
| Ziel-Adresse | Empfänger der Nachrichten. Leer lassen, wenn nur empfangen wird. |
| Empfangs-Adresse | Wird nach dem Anlegen angezeigt (https://<Ihre Domain>/api/v1/webhook/<ID>), mit Knopf Kopieren. |
| Positionen und Status annehmen | Standard eingeschaltet. Ausgeschaltet lehnt Lagewerk Positionen und Status dieser Anbindung mit 403 ab. |
| Eingänge annehmen | Standard ausgeschaltet. Erst eingeschaltet nimmt die Anbindung Alarmeingänge an; sonst 403. |
| Zeitlimit (Sekunden) | Wartezeit beim Senden, 1–60, Standard 10. |
| Empfangs-Token | Geheimnis, mit dem sich Absender ausweisen. Pflicht für den Empfang. |
| Token für die Ziel-Adresse | Wird beim Senden als Authorization: Bearer … mitgeschickt (optional). |
| Kennungs-Regel | Leitet die Geräte-Kennung eines Fahrzeugs ab, wenn am Gerät keine gepflegt ist, z. B. {{.Einsatzmittel.Funkrufname}}. |
| Aktiviert | Nur aktivierte Anbindungen empfangen und senden. |

Empfangen
Adresse und Anmeldung
POST https://<Ihre Domain>/api/v1/webhook/<ID der Anbindung>
Content-Type: application/json
Authorization: Bearer <Empfangs-Token>
Statt des Headers geht auch der Parameter ?token=<Empfangs-Token> an der Adresse, für Absender,
die keine Header setzen können. Der Header ist vorzuziehen, weil Adressen in Protokollen landen.
Ein falsches Token, eine unbekannte oder deaktivierte Anbindung und eine Anbindung eines anderen Typs beantwortet Lagewerk gleich mit 404. So verrät die öffentliche Adresse nicht, welche Anbindungen es gibt.
Antworten
| Status | Bedeutung |
|---|---|
| 204 | Angenommen. Kein Inhalt. |
| 400 | Anfrage ungültig: kein gültiges JSON, unbekanntes Feld, Pflichtfeld fehlt, Wert außerhalb des Bereichs, Position nicht zuordenbar. Der Text nennt den Grund. |
| 403 | Die Anbindung hat diesen Teil nicht freigegeben (Positionen und Status bzw. Eingänge). |
| 404 | Anbindung oder Token passt nicht (siehe oben). |
| 409 | Status abgelehnt, etwa weil der Statuswechsel als Folgestatus nicht zulässig ist oder die Kennung keinem Fahrzeug zugeordnet ist. |
| 429 | Zu viele Anfragen (siehe Grenzen). |
| 503 | Anbindungen sind nicht verfügbar (fehlender SECRETS_KEY) bzw. Anhänge ohne Objektspeicher. |
Fehlerantworten sind JSON mit dem Feld error, zum Beispiel
{"error":"status 12 außerhalb 0..9"}.
Grenzen
- Drosselung: höchstens 600 Anfragen je Minute und Anbindung sowie 1200 je Minute und Absender-IP.
- Größe: Eine Anfrage darf etwa das 1,33-Fache der Upload-Grenze (
MAX_UPLOAD_MB, Standard 20 MB) plus 1 MB groß sein, damit base64-kodierte Anhänge hineinpassen. Größere Anfragen scheitern mit 400. - Unbekannte Felder sind nicht erlaubt; Tippfehler in Feldnamen fallen so sofort auf (400).
Felder einer Anfrage
Eine Anfrage enthält eine Position, einen Status, einen Eingang oder eine Kombination davon.
| Feld | Typ | Bedeutung |
|---|---|---|
external_id |
Text | Kennung des Geräts beim Absender. Pflicht für Position und Status. |
kennungsart |
Text | Art der Kennung, Standard geraete_id. Kleinbuchstaben, Ziffern und _, beginnend mit einem Buchstaben (z. B. issi, seriennummer). |
lat, lon |
Zahl | Position in Grad (WGS 84), nur gemeinsam. Breite −90…90, Länge −180…180. |
speed |
Zahl | Geschwindigkeit (optional). Lagewerk speichert den Wert, zeigt ihn derzeit nicht an. |
heading |
Zahl | Fahrtrichtung in Grad (optional). Wird gespeichert, derzeit nicht angezeigt. |
zeit |
Zeitpunkt | Wann Position oder Status entstanden, RFC 3339 (2026-10-25T14:03:00+02:00). Standard: Eingangszeit. |
status |
Zahl | Fahrzeugstatus 0–9. |
eingang |
Objekt | Ein Alarmeingang, siehe unten. |
Kommen mehrere Teile in einer Anfrage, verarbeitet Lagewerk sie in der Reihenfolge Position, Status, Eingang. Scheitert ein Teil, bricht die Anfrage dort ab; schon verarbeitete Teile bleiben gespeichert.
Zuordnung zum Fahrzeug
Positionen und Status tragen eine Kennung (kennungsart + external_id). Lagewerk sucht dazu:
- ein Gerät mit genau dieser Kennung an einem Einsatzmittel (gepflegt unter dem Einsatzmittel im Abschnitt Geräte),
- sonst die Kennungs-Regel der Anbindung über alle Einsatzmittel,
- sonst wird die Meldung abgelehnt und unter Unbekannte Kennungen gezählt. Von dort lässt sich das Gerät beim richtigen Einsatzmittel anlegen.
Das gefundene Gerät muss aktiv sein und die Funktion Standort (für Positionen) bzw. Status haben (siehe Anbindungen, Gateways und Geräte).
Position melden
curl -X POST "https://lagewerk.example.org/api/v1/webhook/<ID>" \
-H "Authorization: Bearer <Empfangs-Token>" \
-H "Content-Type: application/json" \
-d '{
"external_id": "TRK-0815",
"lat": 49.3501,
"lon": 8.1392,
"speed": 48,
"heading": 270,
"zeit": "2026-10-25T14:03:00+02:00"
}'
Die Position erscheint auf der Karte beim Fahrzeug und in seiner Positionshistorie.
Status melden
curl -X POST "https://lagewerk.example.org/api/v1/webhook/<ID>" \
-H "Authorization: Bearer <Empfangs-Token>" \
-H "Content-Type: application/json" \
-d '{ "external_id": "TRK-0815", "status": 3, "zeit": "2026-10-25T14:05:00+02:00" }'
Für einen Status gelten dieselben Regeln wie für einen Klick im Statustableau:
- Nur zulässige Folgestatus werden angenommen, sonst 409.
- Status 0 und 5 werden zum Sprechwunsch (0 = priorisiert) statt zum Statuswechsel.
- Status 2 beendet die Zuteilung des Fahrzeugs; war es das letzte Fahrzeug, kann sich der Einsatz automatisch schließen.
- Ist
zeitälter als der letzte Statuswechsel des Fahrzeugs, verwirft Lagewerk die Meldung still (Antwort 204), damit nachgereichte alte Meldungen keinen neueren Stand überschreiben. - Die Statushistorie nennt die Anbindung als Quelle.
Position und Status lassen sich in einer Anfrage verbinden:
{ "external_id": "TRK-0815", "lat": 49.3501, "lon": 8.1392, "status": 4 }
Alarmeingang melden
Ein Alarmeingang ist ein Einsatz-Kandidat, der in der Einsatzliste unter Eingehend erscheint (Bedienung siehe Alarmeingänge). Er braucht die Freigabe Eingänge annehmen.
Feld in eingang |
Typ | Bedeutung |
|---|---|---|
external_id |
Text | Pflicht. Kennung des Vorgangs beim Absender; zusammen mit art und der Anbindung eindeutig. |
art |
Text | Optional, Standard eingang. Trennt verschiedene Vorgangsarten desselben Absenders. |
titel |
Text | Anzeige in der Liste und im Tagebuch, z. B. „Brand Lagerhalle“. |
vorschlag |
Objekt | Einsatzfelder zur Vorbelegung, siehe nächste Tabelle. |
daten |
beliebiges JSON | Rohdaten des Absenders; Lagewerk speichert sie, wertet sie aber nicht aus. |
geschlossen |
Wahrheitswert | true archiviert einen noch offenen Eingang („in der Quelle geschlossen“). |
anhaenge |
Liste | Höchstens 20 Dateien, siehe unten. |
Felder im vorschlag (Namen wie beim Anlegen eines Einsatzes; andere Felder → 400):
| Feld | Bedeutung | Feld | Bedeutung |
|---|---|---|---|
report_image |
Meldebild (Freitext-Teil) | target_object_name |
Zielobjekt |
einsatzcodes |
Einsatzcodes, leerzeichengetrennt ("017 901"), je Eintrag auch mit Beschreibung ("017 Schlaganfall; 17A Sturz"); werden Bausteine des Meldebilds vor report_image, Codes ohne Einsatzcode in der aktiven Fassung als grauer Baustein |
target_street |
Zielstraße |
priority |
Priorität (Zahl) | target_house_number |
Ziel-Hausnummer |
bks |
BKS-Meldebild | target_address_extra |
Ziel-Adresszusatz |
tki |
TKI (gilt als von Hand gesetzt) | target_postal_code |
Ziel-PLZ |
object_name |
Objekt | target_city |
Zielort |
street |
Straße | target_district |
Ziel-Ortsteil |
house_number |
Hausnummer | target_country |
Zielland (Kürzel) |
address_extra |
Stockwerk/Adresszusatz | target_lat, target_lon |
Zielkoordinaten (nur gemeinsam) |
postal_code |
PLZ | target_note |
Hinweis zum Zielort |
city |
Ort | caller_name |
Anrufer |
district |
Ortsteil | caller_phone |
Rückrufnummer |
country |
Land (ISO-Kürzel, z. B. DE) |
note |
Notiz |
lat, lon |
Koordinaten (nur gemeinsam) | additional_info |
Zusatzinformationen |
Anhänge (anhaenge): je Datei ein Objekt mit
| Feld | Bedeutung |
|---|---|
dateiname |
Pflicht, z. B. depesche.pdf. |
typ |
MIME-Typ, z. B. application/pdf; Standard application/octet-stream. |
inhalt |
Dateiinhalt, base64-kodiert. |
Anhänge brauchen den Objektspeicher. Bis zur Übernahme stehen sie am Eingang (Hinweis in der Neuanlage), danach am ersten Tagebucheintrag des Einsatzes.
Neuer Eingang mit Anhang:
curl -X POST "https://lagewerk.example.org/api/v1/webhook/<ID>" \
-H "Authorization: Bearer <Empfangs-Token>" \
-H "Content-Type: application/json" \
-d '{
"eingang": {
"external_id": "2026-4711",
"titel": "Brand Lagerhalle",
"vorschlag": {
"bks": "B3",
"report_image": "Rauch aus Lagerhalle",
"priority": 2,
"street": "Hauptstraße",
"house_number": "1",
"postal_code": "67433",
"city": "Neustadt",
"country": "DE",
"lat": 49.3501,
"lon": 8.1392,
"caller_name": "Leitstelle",
"caller_phone": "06321 0000"
},
"daten": { "leitstellen_nr": "4711", "alarmiert": "2026-10-25T14:00:00+02:00" },
"anhaenge": [
{ "dateiname": "depesche.txt", "typ": "text/plain", "inhalt": "RGVwZXNjaGU=" }
]
}
}'
Folgemeldungen
Dieselbe external_id (mit derselben art) noch einmal zu schicken, aktualisiert den Vorgang:
- Offener Eingang: Die mitgeschickten Felder ersetzen die bisherigen, neue Anhänge kommen dazu.
- Übernommener Eingang: Die Meldung fließt in den Einsatz. Ein Feld übernimmt den neuen Wert nur, wenn es im Einsatz noch dem zuletzt gemeldeten Wert entspricht. Hat es jemand geändert, bleibt es, und das Tagebuch nennt den neuen Wert der Quelle.
- Archivierter Eingang oder archivierter Einsatz: Die Meldung wird ignoriert (204).
Dabei zählen nur die mitgeschickten Felder:
Im vorschlag |
Wirkung |
|---|---|
| Feld fehlt | bleibt unverändert |
| Feld mit Wert | wird übernommen (sofern nicht von Hand geändert) |
Feld mit "" bzw. null |
wird geleert (sofern nicht von Hand geändert) |
Ein Feld, das die Quelle zum ersten Mal meldet, vergleicht Lagewerk mit dem Wert bei der Anlage (leer, Priorität 3). Was dort von Hand eingetragen wurde, bleibt also stehen.
Nur das BKS-Meldebild ändern (Adresse und alle anderen Felder bleiben):
{ "eingang": { "external_id": "2026-4711", "vorschlag": { "bks": "B4" } } }
Ein Feld leeren:
{ "eingang": { "external_id": "2026-4711", "vorschlag": { "caller_phone": "" } } }
Vorgang in der Quelle geschlossen (archiviert nur einen noch offenen Eingang):
{ "eingang": { "external_id": "2026-4711", "geschlossen": true } }
Bringt eine Folgemeldung neue Einsatzcodes oder ein geändertes BKS-Meldebild, legen die Aufgabenvorlagen mit Auslöser „Einsatzcode oder BKS-Meldebild kommt hinzu“ ihre Aufgaben an; technische Aufgaben starten dabei nicht von selbst, sondern warten auf Ausführen.
Test im Entwicklungs-Stack
Der Entwicklungs-Stack unter https://elw.localhost nutzt ein selbst ausgestelltes Zertifikat.
curl lehnt die Verbindung dann ab; ergänzen Sie dort -k oder geben Sie das Wurzelzertifikat
des Caddy-Containers mit --cacert an. Im Betrieb mit gültigem Zertifikat ist beides nicht nötig.
Senden: Funktion „Nachricht“
Technische Aufgaben schicken mit der Funktion Nachricht über eine Webhook-Anbindung (siehe Funktionen und Ziele und Aufgaben am Einsatz). Üblich ist das Ziel Anbindung direkt; mit einem anderen Ziel geht die Nachricht nur dann über den Webhook, wenn das Gerät dort eine Kennung hat. Voraussetzung ist eine Ziel-Adresse an der Anbindung.
Angaben
| Angabe | Bedeutung |
|---|---|
| Betreff | Optional, höchstens 200 Zeichen, mit Platzhaltern. |
| Text | Pflicht, höchstens 2000 Zeichen, mit Platzhaltern (Textvorlage, siehe unten). |
| Ereignis | Zusatzangabe des Webhooks (nur bei Ziel „Anbindung direkt“): frei wählbare Kennung für den Empfänger, z. B. alarm; höchstens 100 Zeichen. |
Anfrage an die Ziel-Adresse
POST <Ziel-Adresse>
Content-Type: application/json
Idempotency-Key: <ID des Versands>
Authorization: Bearer <Token für die Ziel-Adresse> (nur wenn hinterlegt)
{
"id": "5f0c…",
"funktion": "nachricht",
"ereignis": "alarm",
"betreff": "",
"text": "Alarm B3 Hauptstraße 1",
"einsatz": {
"id": "9a70…",
"nummer": "E-2026-0042",
"meldebild": "Rauch aus Lagerhalle",
"bks": "B3",
"objekt": "",
"adresse": "Hauptstraße 1",
"ort": "67433 Neustadt",
"bemerkung": "",
"prioritaet": 2,
"lat": 49.3501,
"lon": 8.1392
},
"einsatzmittel": {
"id": "3c1e…",
"funkrufname": "RTW 1",
"kennung": "TRK-0815",
"kennungsart": "geraete_id"
},
"aufgabe": { "id": "77ab…", "titel": "Leitstelle informieren" },
"gesendet_at": "2026-10-25T13:05:00Z"
}
idist die Versandnummer; sie steht auch im HeaderIdempotency-Key. Wiederholungen desselben Versands tragen dieselbe Nummer, der Empfänger kann Doppelte daran erkennen.einsatzmittelist das zuständige, sonst das auslösende Fahrzeug der Aufgabe;kennungundkennungsartnur, wenn diese Anbindung das Fahrzeug adressieren kann.lat/londes Einsatzes fehlen, wenn er keine Koordinaten hat,einsatzcodes,bksundtki, wenn sie leer sind.- Die Daten zeigen den Stand beim Auslösen der Aufgabe.
Antwort des Empfängers
| Antwort | Folge |
|---|---|
| 2xx | Erfolg; die Aufgabe ist erledigt. HTTP-Status und die ersten 500 Byte der Antwort stehen am Ergebnis. |
| 408, 429, 5xx, Netzfehler, Zeitlimit | Lagewerk wiederholt den Versand mit wachsendem Abstand, höchstens 20 Versuche. |
| andere Antworten (z. B. 400, 401, 404) | Endgültig fehlgeschlagen; die Aufgabe zeigt den Fehler. |
Der Versand läuft über die Warteschlange (Verwaltung → Anbindungen → Ausgang), je Anbindung
strikt der Reihe nach. Ziel-Adressen im internen Netz sind gesperrt, bis der Betrieb ihr Netz
über EGRESS_ALLOWED_NETS freigibt.
Platzhalter im Text
Betreff und Text sind Textvorlagen. Platzhalter stehen in doppelten geschweiften Klammern:
| Platzhalter | Inhalt |
|---|---|
{{.Einsatz.Nummer}} |
Einsatznummer |
{{.Einsatz.Meldebild}} |
Meldebild als Klartext (Codes und Freitext) |
{{.Einsatz.Einsatzcodes}} |
Einsatzcodes, leerzeichengetrennt, z. B. „017 901“ |
{{.Einsatz.Bks}} |
BKS-Meldebild |
{{.Einsatz.Tki}} |
TKI |
{{.Einsatz.Objekt}} |
Objekt |
{{.Einsatz.Adresse}} |
Straße und Hausnummer |
{{.Einsatz.Ort}} |
PLZ und Ort |
{{.Einsatz.Bemerkung}} |
Notiz |
{{.Einsatz.Prioritaet}} |
Priorität |
{{.Einsatz.ID}} |
interne ID des Einsatzes |
{{.Einsatzmittel.Funkrufname}} |
Funkrufname des Fahrzeugs |
{{.Einsatzmittel.Kennung}} |
Kennung des Fahrzeugs bei dieser Anbindung |
{{.Einsatzmittel.KennungsArt}} |
Art dieser Kennung |
{{.Aufgabe.Titel}} |
Titel der Aufgabe |
{{kuerze 50 .Einsatz.Meldebild}} |
Text auf höchstens 50 Zeichen gekürzt |
Beispiel: Alarm {{.Einsatz.Bks}} – {{.Einsatz.Adresse}}, {{.Einsatz.Ort}}. Unbekannte
Platzhalter lehnt Lagewerk schon beim Speichern der Vorlage ab.