Webhooks

Echtzeit-Benachrichtigungen erhalten, wenn Ereignisse auftreten.

Übersicht

Webhooks ermöglichen Ihnen:

• Sofortige Ereignisbenachrichtigungen zu erhalten
• Workflows zu automatisieren
• Mit externen Systemen zu synchronisieren
• Reaktive Integrationen zu erstellen

Tarifanforderung

Webhook-Zugang erfordert einen Tarif, der API-Funktionen enthält.

Wie Webhooks funktionieren

1. Sie konfigurieren eine Endpunkt-URL
2. Wählen Sie Ereignisse zum Abonnieren
3. Wenn Ereignisse auftreten, senden wir HTTP-POST-Anfragen
4. Ihr Server verarbeitet den Payload
5. Sie antworten mit 2xx-Status

Verfügbare Ereignisse

Ereignis	Beschreibung
photo_request.created	Neue Fotoanfrage erstellt
photo_request.first_viewed	Anfrage zum ersten Mal angesehen
photo_submission.created	Fotos eingereicht (Permanente Links)
photo_request.submitted	Einmalige Anfrage abgeschlossen
photo_request.expired	Anfrage ohne Einreichung abgelaufen
photo_submission.dropbox_synced	Foto mit Freigabelink zu Dropbox synchronisiert

Webhook erstellen

Schritte

1. Gehen Sie zu Webhooks in der Seitenleiste
2. Klicken Sie auf Webhook erstellen
3. Geben Sie einen beschreibenden Namen ein
4. Geben Sie Ihre Endpunkt-URL an
5. Wählen Sie Ereignisse zum Abonnieren
6. Aktivieren Sie Aktiv (Standard: an)
7. Klicken Sie auf Erstellen

Endpunkt-Anforderungen

Anforderung	Wert
Protokoll	HTTPS erforderlich
Erreichbarkeit	Öffentliches Internet
Antwort	2xx-Statuscode
Timeout	Maximal 30 Sekunden

Private Netzwerke

Private und interne Netzwerkadressen (localhost, 10.x.x.x, 192.168.x.x) sind nicht erlaubt.

Webhook-Payload

Anfrageformat

POST /ihr-endpunkt HTTP/1.1
Host: ihr-server.com
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-ID: wh_123456
X-Webhook-Timestamp: 1609459200

Payload-Struktur

{
  "event": "photo_request.submitted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "type": "one_time",
    "instructions": "Fotos des Fahrzeugs senden",
    "photos": [
      {
        "id": "photo_xyz789",
        "url": "https://...",
        "slot_instructions": "Vorderansicht",
        "metadata": {
          "gps_lat": 45.1234,
          "gps_lng": 12.5678,
          "captured_at": "2024-01-15T10:28:00Z"
        }
      }
    ],
    "submitted_at": "2024-01-15T10:30:00Z"
  }
}

Signaturverifizierung

Warum verifizieren

Verifizieren Sie Webhook-Signaturen, um sicherzustellen:

• Anfrage kam von Visiono
• Payload wurde nicht manipuliert
• Replay-Angriffe verhindern

Signatur-Header

X-Webhook-Signature: sha256=abc123def456...

Verifizierungsschritte

// PHP-Beispiel
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'ihr-webhook-secret';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Ungültige Signatur');
}

// Node.js-Beispiel
const crypto = require('crypto');

const payload = JSON.stringify(req.body);
const signature = req.headers['x-webhook-signature'];
const secret = process.env.WEBHOOK_SECRET;

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  return res.status(401).send('Ungültige Signatur');
}

Webhooks verwalten

Webhook testen

Testereignis senden:

1. Klicken Sie auf Test beim Webhook
2. Bestätigen Sie die Aktion
3. Prüfen Sie Antwortstatus
4. Bei Fehlschlag in Logs anzeigen

Logs anzeigen

Zustellungsverlauf sehen:

1. Klicken Sie auf Logs beim Webhook
2. Kürzliche Zustellungen anzeigen
3. Status und Antwort prüfen
4. Fehler debuggen

Log-Details

Jeder Log zeigt:

• Ereignistyp
• Zeitstempel
• Antwortstatus
• Antwortzeit
• Anfrage-/Antwortkörper (für Debugging)

Secret regenerieren

Neues Signatur-Secret erhalten:

1. Klicken Sie auf Secret regenerieren
2. Bestätigen Sie die Aktion
3. Neues Secret sofort kopieren
4. Ihren Server aktualisieren

Server zuerst aktualisieren

Nach dem Regenerieren funktioniert das alte Secret nicht mehr. Aktualisieren Sie Ihren Verifizierungscode vor dem Regenerieren.

Webhook deaktivieren

Vorübergehend keine Ereignisse mehr empfangen:

1. Klicken Sie auf Deaktivieren
2. Bestätigen Sie die Aktion
3. Ereignisse werden nicht mehr gesendet
4. Bei Bedarf wieder aktivieren

Webhook löschen

Dauerhaft entfernen:

1. Klicken Sie auf Löschen
2. Bestätigen Sie die Aktion
3. Alle Logs werden gelöscht

Retry-Richtlinie

Automatische Wiederholungen

Fehlgeschlagene Zustellungen werden wiederholt:

Versuch	Verzögerung
1	Sofort
2	1 Minute
3	5 Minuten
4	30 Minuten
5	2 Stunden

Fehlerkriterien

Eine Zustellung schlägt fehl, wenn:

• Verbindungs-Timeout (30s)
• Nicht-2xx-Antwort
• Netzwerkfehler
• SSL-Fehler

Nach maximalen Wiederholungen

Wenn alle Wiederholungen fehlschlagen:

• Ereignis wird als fehlgeschlagen markiert
• Zur Überprüfung protokolliert
• Keine weiteren Versuche

Best Practices

Endpunkt-Design

• Schnell antworten (< 5 Sekunden)
• Bei Bedarf asynchron verarbeiten
• Sofort 2xx zurückgeben
• Idempotenz handhaben

Fehlerbehandlung

// Empfohlenes Muster
app.post('/webhook', async (req, res) => {
  // Zuerst Signatur verifizieren
  if (!verifySignature(req)) {
    return res.status(401).send('Ungültig');
  }

  // Sofort bestätigen
  res.status(200).send('OK');

  // Asynchron verarbeiten
  processWebhookAsync(req.body);
});

Idempotenz

Ereignisse können mehr als einmal gesendet werden. Duplikate handhaben:

// Prüfen, ob bereits verarbeitet
const eventId = req.headers['x-webhook-id'];
if (await isProcessed(eventId)) {
  return res.status(200).send('Bereits verarbeitet');
}

// Verarbeiten und als behandelt markieren
await processEvent(req.body);
await markProcessed(eventId);

Überwachung

• Alle eingehenden Webhooks protokollieren
• Bei Fehlern alarmieren
• Antwortzeiten überwachen
• Ereignisvolumen verfolgen

Fehlerbehebung

Keine Ereignisse empfangen

1. Verifizieren, dass Webhook aktiv ist
2. Prüfen, dass Endpunkt-URL korrekt ist
3. Sicherstellen, dass HTTPS funktioniert
4. Verifizieren, dass Server erreichbar ist
5. Ausgewählte Ereignisse prüfen

Signatur-Mismatch

1. Richtiges Secret verwenden
2. Vollständigen Payload vergleichen (nicht geparst)
3. Auf Encoding-Probleme prüfen
4. HMAC-Algorithmus verifizieren (SHA256)

Timeouts

1. Verarbeitungszeit reduzieren
2. Sofort bestätigen
3. Asynchron verarbeiten
4. Serverressourcen prüfen

Fehlgeschlagene Zustellungen anzeigen

1. Zu Webhook-Logs gehen
2. Nach Status filtern (fehlgeschlagen)
3. Anfrage-/Antwortdetails anzeigen
4. Beheben und erneut testen

Webhook-Limits

Pro Tarif

Tarif	Max. Webhooks
Professional	5 Webhooks
Enterprise	Unbegrenzt

Rate-Limits

Limit	Wert
Ereignisse pro Minute	100
Payload-Größe	1 MB

Verwandte Seiten

• API-Schlüssel - API-Authentifizierung
• API-Referenz - Vollständige API-Dokumentation
• Integrationen - Vorgefertigte Integrationen