Webhooks

Webhook-Konfiguration

Umbrella sendet Webhook-Benachrichtigungen an Ihre externen Systeme, wenn Garantieereignisse eintreten. Mit Webhooks binden Sie Ihr CRM, Ihren Support-Desk, Ihre Analysetools oder Ihre Backend-Dienste an.

---

Ereignistypen

Policen-Ereignisse

Ereignis	Beschreibung
policy.created	Garantiepolice erstellt (Bestellung mit Garantie abgeschlossen)
policy.activated	Police aktiviert (Zahlung bestätigt)
policy.expired	Police hat ihr Enddatum erreicht
policy.cancelled	Police storniert (Erstattung oder Stornierung der Bestellung)
policy.updated	Police aktualisiert (Änderung von Status oder Metadaten)

Anspruchs-Ereignisse

Ereignis	Beschreibung
claim.created	Neuer Anspruch eingereicht
claim.updated	Anspruchsstatus geändert
claim.approved	Anspruch genehmigt
claim.denied	Anspruch abgelehnt
claim.resolved	Anspruch gelöst (Ersatz versandt oder Erstattung ausgestellt)

Bestell-Ereignisse

Ereignis	Beschreibung
order.warranty_attached	Garantie einer Bestellposition hinzugefügt
order.warranty_removed	Garantie aus einer Bestellung entfernt
order.post_purchase_completed	Post-Purchase-Garantie-Upsell abgeschlossen

Kunden-Ereignisse

Ereignis	Beschreibung
customer.policy_assigned	Police einem Kunden zugewiesen
customer.claim_filed	Kunde hat einen Anspruch eingereicht

---

Payload-Format

Alle Payloads haben diese Struktur:

{
  "id": "wh_evt_abc123def456",
  "event": "policy.created",
  "timestamp": "2026-03-17T14:30:00.000Z",
  "version": "1.0",
  "data": { ... },
  "metadata": {
    "orgId": "org_abc",
    "integrationPlatform": "shopify",
    "shopDomain": "my-store.myshopify.com"
  }
}

• id — eindeutige Ereignis-ID (zur Deduplizierung verwenden)
• event — Ereignistyp
• data — ereignisspezifischer Payload mit Details zur Ressource
• metadata — Kontext zu Organisation und Integration

---

Signaturprüfung

Alle Webhooks enthalten einen X-Umbrella-Signature-Header (HMAC-SHA256 des Request-Bodys). Prüfen Sie ihn immer vor der Verarbeitung. Codebeispiele zur Prüfung finden Sie in der Webhook-Referenz.

---

Wiederholungsstrategie

Fehlgeschlagene Zustellungen (Antwort außerhalb von 2xx oder Zeitüberschreitung) werden mit exponentiellem Backoff wiederholt:

Versuch	Verzögerung
1. Wiederholung	30 Sekunden
2. Wiederholung	2 Minuten
3. Wiederholung	10 Minuten
4. Wiederholung	1 Stunde
5. Wiederholung	6 Stunden
Letzte Wiederholung	24 Stunden

Ihr Endpunkt muss innerhalb von 30 Sekunden mit 200, 201 oder 202 antworten. Antworten Sie sofort und verarbeiten Sie asynchron, um Zeitüberschreitungen zu vermeiden.

---

Einen Endpunkt einrichten

1. Gehen Sie zu Dashboard → Einstellungen → Webhooks
2. Klicken Sie auf Endpunkt hinzufügen
3. Geben Sie die HTTPS-URL Ihres Endpunkts ein und wählen Sie die Ereignisse aus
4. Kopieren Sie das Signatur-Secret und bewahren Sie es sicher auf (es wird nur einmal angezeigt)
5. Testen Sie mit Testereignis senden auf der Detailseite des Endpunkts

---

Webhook-Protokolle

Die Protokollseite zeigt den Zustellverlauf pro Endpunkt: Ereignistyp, Status (erfolgreich/fehlgeschlagen/wiederholt), Antwortcode, Antwortzeit, Zeitstempel und Anzahl der Versuche.

---

Verwandte Themen

• Shopify-Produktsynchronisierung — Synchronisierung über Shopify-Webhooks
• Shopify-Integration — Die Shopify-Verbindung insgesamt
• Widget-Konfiguration — Anzeigeeinstellungen des Widgets