Webhooks-Referenz

Webhooks senden HTTP-POST-Anfragen an Ihren Endpunkt, sobald in Umbrella Ereignisse eintreten. So müssen Sie die API nicht nach Änderungen abfragen.

Einrichtung

1. Öffnen Sie Dashboard > Einstellungen > Integrationen > Webhooks
2. Klicken Sie auf Webhook-Endpunkt hinzufügen
3. Geben Sie die HTTPS-URL Ihres Endpunkts ein
4. Wählen Sie die Ereignisse aus, die Sie empfangen möchten
5. Speichern Sie und bewahren Sie das Signatur-Secret auf (es wird nur einmal angezeigt)

Ihr Endpunkt muss POST-Anfragen annehmen, innerhalb von 30 Sekunden einen 2xx-Status zurückgeben und application/json akzeptieren.

Ereignistypen

Policen-Ereignisse

Anspruchs-Ereignisse

Registrierungs-Ereignisse

Garantie-Ereignisse

Payload-Struktur

Jeder Webhook verwendet diese Hülle:

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "claim.submitted",
  "timestamp": "2025-03-15T14:30:00.000Z",
  "apiVersion": "1.3.9",
  "orgId": "org_xyz789",
  "data": { ... }
}

• id — eindeutige Ereignis-ID (zur Deduplizierung verwenden)
• type — Ereignistyp
• timestamp — Zeitpunkt des Ereignisses
• data — ereignisspezifische Payload mit den Details der betroffenen Ressource (Police, Anspruch, Registrierung usw.)

Signaturprüfung

Jede Anfrage enthält einen Header X-Umbrella-Signature mit einem HMAC-SHA256-Hash des Request-Bodys. Prüfen Sie diesen, bevor Sie Ereignisse verarbeiten.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Wiederholungsstrategie

Fehlgeschlagene Zustellungen (kein 2xx, Timeout, Verbindungsfehler) werden mit exponentiellem Backoff wiederholt:

Nach 7 fehlgeschlagenen Versuchen wird die Zustellung als fehlgeschlagen markiert. Eine Antwort 410 Gone deaktiviert den Endpunkt dauerhaft.

Testen

1. Öffnen Sie Dashboard > Einstellungen > Integrationen > Webhooks
2. Klicken Sie auf Ihren Endpunkt und dann auf Testereignis senden
3. Wählen Sie einen Ereignistyp und prüfen Sie das Zustellergebnis

Die Detailseite des Webhooks zeigt außerdem ein Protokoll der letzten Zustellungen mit Statuscodes und Laufzeiten.

Verwandte Themen

• Authentifizierung — API-Sicherheit und Zugangsdaten
• Claims API — Endpunkte zur Verwaltung von Ansprüchen
• Policen-API — Endpunkte zur Verwaltung von Policen