Webhooks

Webhooks senden Echtzeit-HTTP-Benachrichtigungen, wenn Ereignisse in Ihrer Flotte auftreten. Erhalten Sie sofortige Updates für Fahrten, Fahrzeugstatusänderungen, Kundenaktionen und mehr.

Übersicht

Was Webhooks bewirken

Anstatt die API abzufragen, senden Webhooks Updates an Sie:

Ereignis tritt auf → Levy sendet HTTP POST → Ihr Server empfängt Daten

Anwendungsfälle

• Echtzeit-Dashboards
• Externe Alarmsysteme
• Datensynchronisation
• Abrechnungsintegrationen
• Analyseplattformen
• Benutzerdefinierte Benachrichtigungen

Webhooks einrichten

Webhook-Endpunkt erstellen

1. Navigieren Sie zu Einstellungen > Webhooks
2. Klicken Sie auf Webhook hinzufügen
3. Konfigurieren Sie:
   • Endpunkt-URL
   • Zu empfangende Ereignisse
   • Geheimschlüssel (zur Verifizierung)
4. Klicken Sie auf Erstellen

Konfigurationsoptionen

URL-Anforderungen

Ihr Endpunkt muss:

• HTTPS verwenden
• Eine 2xx-Antwort zurückgeben
• Innerhalb von 30 Sekunden antworten
• POST-Anfragen akzeptieren
• JSON-Body verarbeiten

Verfügbare Ereignisse

Fahrtereignisse

Fahrzeugereignisse

Kundenereignisse

Zahlungsereignisse

IoT-Ereignisse

Ereignis-Payload

Standardstruktur

Alle Ereignisse enthalten:

{
  "id": "evt_abc123",
  "type": "ride.ended",
  "created": "2025-12-25T10:30:00Z",
  "data": {
    // Ereignisspezifische Daten
  },
  "account_id": "acc_xyz789"
}

Beispiel: Fahrt beendet

{
  "id": "evt_abc123",
  "type": "ride.ended",
  "created": "2025-12-25T10:30:00Z",
  "data": {
    "ride_id": "ride_456",
    "customer_id": "cust_789",
    "vehicle_id": "veh_012",
    "duration_minutes": 15,
    "distance_km": 2.5,
    "fare": 5.50,
    "start_location": {
      "lat": 40.7128,
      "lng": -74.0060
    },
    "end_location": {
      "lat": 40.7200,
      "lng": -74.0100
    }
  }
}

Beispiel: Fahrzeugstatus geändert

{
  "id": "evt_def456",
  "type": "vehicle.status_changed",
  "created": "2025-12-25T11:00:00Z",
  "data": {
    "vehicle_id": "veh_012",
    "vehicle_number": "LV-001",
    "previous_status": "available",
    "new_status": "in_use",
    "battery_level": 85,
    "location": {
      "lat": 40.7128,
      "lng": -74.0060
    }
  }
}

Webhooks verifizieren

Signaturverifizierung

Jeder Webhook enthält einen Signatur-Header:

X-Levy-Signature: t=1640000000,v1=abc123...

Verifizierungsschritte

1. Zeitstempel und Signatur extrahieren
2. Signierten Payload erstellen
3. Erwartete Signatur berechnen
4. Signaturen vergleichen

Beispiel (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const [t, v1] = signature.split(',');
  const timestamp = t.split('=')[1];
  const sig = v1.split('=')[1];

  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return sig === expected;
}

Zeitstempel-Validierung

Replay-Angriffe verhindern:

• Prüfen Sie, ob der Zeitstempel aktuell ist (< 5 Minuten)
• Alte Webhooks ablehnen

Webhooks verarbeiten

Antwortanforderungen

Ihr Endpunkt sollte:

• Status 200-299 zurückgeben
• Schnell antworten (< 30s)
• Bei langsamer Verarbeitung asynchron arbeiten

Wiederholungsrichtlinie

Fehlgeschlagene Zustellungen werden wiederholt:

Nach 5 Fehlversuchen wird der Webhook pausiert.

Idempotenz

Ereignisse können mehrfach zugestellt werden:

• Verwenden Sie die Ereignis-id zur Deduplizierung
• Gestalten Sie Handler idempotent
• Speichern Sie verarbeitete Ereignis-IDs

Webhooks verwalten

Webhooks anzeigen

Die Webhooks-Seite zeigt:

• Alle konfigurierten Webhooks
• Ereignisabonnements
• Zustellungsstatus
• Letzte Zustellungszeit

Webhooks testen

Testereignisse senden:

1. Auf Webhook klicken
2. Test senden klicken
3. Ereignistyp auswählen
4. Zustellungsergebnis anzeigen

Zustellungsprotokolle anzeigen

Zustellungsverlauf einsehen:

• Zeitstempel
• Ereignistyp
• Antwortstatus
• Antwortinhalt
• Wiederholungsversuche

Webhooks deaktivieren

Um Zustellungen zu pausieren:

1. Auf Webhook klicken
2. Aktiv ausschalten
3. Ereignisse werden gesammelt (bis zu 24h)

Webhooks löschen

Zum Entfernen:

1. Auf Webhook klicken
2. Löschen klicken
3. Löschung bestätigen

Ereignisfilterung

Nach Ereignistyp

Spezifische Ereignisse auswählen:

• Alle Ereignisse
• Nur Fahrtereignisse
• Nur Fahrzeugereignisse
• Benutzerdefinierte Auswahl

Nach Unterkonto

Nach Standort filtern:

• Alle Unterkonten
• Bestimmte Unterkonten
• Einzelnes Unterkonto

Nach Bedingungen

Erweiterte Filterung:

• Fahrzeugmodell
• Statusänderungen
• Schwellenwerte

Best Practices

Endpunkt-Design

• Dedizierten Webhook-Endpunkt verwenden
• Sofort 200 zurückgeben
• Asynchron verarbeiten
• Alle Zustellungen protokollieren

Fehlerbehandlung

• Fehlerhafte Payloads behandeln
• Signaturen immer verifizieren
• Timeout-Behandlung implementieren
• Bei wiederholten Fehlern alarmieren

Sicherheit

• Nur HTTPS verwenden
• Signaturen verifizieren
• Zeitstempel validieren
• Geheimschlüssel-Rotation nutzen

Skalierbarkeit

• Nachrichtenwarteschlangen verwenden
• Spitzenlasten elegant bewältigen
• Endpunkt nach Bedarf skalieren
• Latenz überwachen

Webhook-Szenarien

Echtzeit-Dashboard

Ereignis: ride.started → Live-Fahrtanzahl aktualisieren
Ereignis: ride.ended → Umsatz berechnen
Ereignis: vehicle.status_changed → Karte aktualisieren

Alarmsystem

Ereignis: vehicle.low_battery → Ops-Team alarmieren
Ereignis: vehicle.offline → Ticket erstellen
Ereignis: iot.alarm → Benachrichtigung auslösen

Analyse-Pipeline

Alle Ereignisse → Nachrichtenwarteschlange → Analyse-Prozessor → Datenbank

Fehlerbehebung

Webhooks werden nicht empfangen

1. Prüfen Sie, ob der Endpunkt erreichbar ist
2. Prüfen Sie, ob der Webhook aktiv ist
3. Überprüfen Sie die Ereignisauswahl
4. Serverprotokolle prüfen

Signaturverifizierung fehlgeschlagen

1. Prüfen Sie, ob der Geheimschlüssel korrekt ist
2. Payload-Parsing prüfen
3. Zeitstempel-Behandlung validieren
4. Implementierung überprüfen

Zustellungen schlagen fehl

1. Prüfen Sie, ob der Endpunkt 2xx zurückgibt
2. Prüfen Sie, ob die Antwortzeit < 30s ist
3. Serverfehler überprüfen
4. Firewall-Regeln prüfen

Doppelte Ereignisse

1. Deduplizierung implementieren
2. Ereignis-ID-Tracking verwenden
3. Handler idempotent gestalten
4. Wiederholungszeitpunkt prüfen

---