#Webhooks einrichten

Ein Webhook ist eine HTTPS-Adresse Ihres Systems. LOGICAR schickt jedes Ereignis, das Sie abonniert haben, als POST mit JSON dorthin — signiert, und bei Fehlschlag nach Plan wiederholt.

Neue Endpunkte bekommen die Ereignisse der API v1 (apiVersion 2026-09-01, Ereignisse). Endpunkte, die vor dem 23.09.2026 angelegt wurden, bekommen weiter das bisherige Format.

#Im Portal anlegen

Unter Einstellungen → Webhooks:

1. Adresse eintragen, z. B. https://erp.example.com/logicar/webhooks.
2. Umgebung wählen: Echtbetrieb oder Sandbox. Ein Endpunkt bekommt nur Ereignisse seiner Umgebung — Testvorgänge erreichen nie Ihren Produktionsendpunkt.
3. Ereignisse wählen (Katalog).
4. Speichern. Das Geheimnis erscheint jetzt einmal — für die Signaturprüfung sicher ablegen. LOGICAR speichert es verschlüsselt und zeigt es danach nicht mehr.

#Über die API anlegen

Ihr System kann seine Endpunkte auch selbst verwalten, mit einem Zugang, der das Recht webhooks:manage hat. Die Umgebung folgt dem Zugang: ein Testschlüssel (lc_test_…) legt Sandbox-Endpunkte an und sieht nur diese.

POST /api/v1/extern/webhook-subscriptions
Authorization: Bearer <Token>
Content-Type: application/json

{
  "url": "https://erp.example.com/logicar/webhooks",
  "events": ["driver.assigned", "vehicle.picked_up", "vehicle.delivered"],
  "description": "SAP Integration Suite"
}

Die Antwort (201) nennt den Endpunkt und einmalig das Geheimnis in secret (64 Hexzeichen). Danach gibt es:

Unbekannte Ereignisse oder Felder ergeben 400 mit der Liste der Felder. Eine Adresse, die die Regeln unten verletzt, ergibt 400 INVALID_WEBHOOK_URL; details.reason sagt warum, etwa HTTPS_REQUIRED oder PRIVATE_ADDRESS.

#Regeln für die Adresse

Damit keine Nachricht in einem fremden oder internen Netz landet, gilt:

• Nur https://.
• Nur öffentlich erreichbare Ziele. Adressen im privaten Netz (10.x, 192.168.x, localhost, Cloud-Metadaten …) werden abgewiesen — auch wenn ein öffentlicher Name dorthin auflöst.
• Weiterleitungen werden nicht verfolgt: antwortet Ihr Endpunkt mit 301 oder 302, gilt die Zustellung als gescheitert. Tragen Sie die endgültige Adresse ein.
• Höchstens zehn Endpunkte je Umgebung.

#Testen

Testnachricht senden (im Portal oder über die API) schickt das Ereignis webhook.test an den Endpunkt — unabhängig davon, was er abonniert hat, im selben Umschlag und mit derselben Signatur wie jede andere Nachricht. Das Ergebnis (Status, Dauer, Antwort) sehen Sie sofort.

Für den ganzen Ablauf: einen Testauftrag in der Sandbox einstellen. Er schickt dieselben Ereignisse wie ein echter Auftrag.

#Geheimnis wechseln

Geheimnis erneuern erzeugt ein neues und zeigt es einmal. Das alte gilt ab sofort nicht mehr — legen Sie das neue in Ihrem System ab, bevor die nächste Nachricht kommt. Tun Sie das, sobald das Geheimnis in falsche Hände geraten sein könnte.

#Pausieren und löschen

Ein pausierter Endpunkt bekommt keine Nachrichten. Noch offene Wiederholungen werden als nicht zustellbar abgelegt (DEAD_LETTER) und lassen sich nach dem Fortsetzen im Protokoll erneut senden. Löschen entfernt den Endpunkt mit seinem Protokoll.

#Protokoll

Zu jedem Endpunkt zeigt das Portal die Zustellungen der letzten Zeit: Ereignis, Stand (DELIVERED, FAILED_RETRYING, DEAD_LETTER), HTTP-Status Ihres Endpunkts, Dauer, Versuche und der Anfang Ihrer Antwort. Jede Zustellung lässt sich erneut senden — etwa nachdem Ihr Endpunkt nach einer Störung wieder läuft (Zustellung).

#Endpunkte im bisherigen Format

Wer vor dem 23.09.2026 einen Endpunkt angelegt hat, bekommt dort weiter das bisherige Format: event statt type, ohne apiVersion, mit den Ereignissen order.status_changed, protocol.* und den übrigen des bisherigen Katalogs. Daran ändert sich nichts, solange Sie nichts ändern.

Im Portal steht an solchen Endpunkten Bisheriges Format und der Knopf Auf API v1 umstellen. Adresse und Geheimnis bleiben; vorgewählt sind die Ereignisse, die Ihren bisherigen entsprechen — prüfen Sie die Auswahl, bevor Sie umstellen. Danach prüft Ihr System type statt event und die Köpfe der API v1. Zurück ins bisherige Format geht es nicht.