131 — Outgoing-Webhooks

Statt aktiv per API zu pollen, können Sie sich von PartnerDesk per Webhook benachrichtigen lassen, wenn bestimmte Events passieren. Damit lassen sich CRMs, Slack, eigene Backend-Systeme effizient anbinden.

Setup

Admin → „Einstellungen" → „Sicherheit & API" → „Webhooks" → „Endpoint hinzufügen":

Feld	Funktion
URL	Ziel-URL (HTTPS empfohlen)
Events	Welche Events abonnieren (Multi-Select)
Aktiv	Master-Switch

Nach Speichern wird ein Secret generiert + einmalig angezeigt — sofort kopieren!

Verfügbare Events

Event	Wird gefeuert wenn
partner.created	Neuer Partner angelegt (Admin, Self-Signup, oder API)
partner.status_changed	Status-Wechsel (z. B. pending → active)
partner.deleted	Partner anonymisiert
transaction.created	Neue Transaction (egal welcher Provider)
transaction.approved	TX wurde approved
transaction.rejected	TX wurde rejected
transaction.refunded	TX als refunded markiert
payout.approved	Payout freigegeben
payout.paid	Payout als bezahlt markiert
payout.cancelled	Payout storniert
customer.assigned	Customer wurde einem Partner zugeordnet
bonus.awarded	Leistungsprämie wurde vergeben
academy.course_completed	Partner hat alle Lektionen eines Kurses abgeschlossen
lead_referral.threshold_reached	Empfehlungs-Schwelle erreicht
lead_referral.campaign_ended	Lead-Referral-Kampagne ist ausgelaufen

Signatur-Validierung

Jeder Webhook-Request enthält:

X-PartnerDesk-Signature: sha256=<hex>

Berechnung auf Empfänger-Seite:

import hmac, hashlib

signature = "sha256=" + hmac.new(
    secret.encode(),
    request_body,
    hashlib.sha256
).hexdigest()

Vergleich mit hmac.compare_digest (timing-safe). Bei Mismatch: Webhook nicht akzeptieren.

Payload-Format

{
  "event": "transaction.approved",
  "timestamp": "2026-05-21T10:00:00Z",
  "tenantSlug": "4leads",
  "data": {
    "id": "uuid-...",
    "partnerId": "P-001",
    "amount": "100.00",
    "commission": "20.00",
    ...
  }
}

Test-Funktion

Im Admin-UI gibt es einen „Test"-Button pro Endpoint, der einen Mock-Event sendet (typischerweise transaction.approved mit Sample-Daten). Verifizieren Sie, ob Ihr Endpoint die Signatur korrekt validiert.

Retry-Strategie

Wenn Ihr Endpoint nicht antwortet (Timeout, 5xx, Netzwerk):

• 5 Retries mit exponentiellem Backoff: 5 s → 10 s → 20 s → 40 s → 80 s.
• Bei 4xx-Response (z. B. 400 Bad Request): kein Retry — PartnerDesk geht davon aus, dass Ihre Seite das Format ablehnt.

Auto-Deactivate

Nach 10 aufeinanderfolgenden Failures wird der Endpoint automatisch auf active=false gesetzt — Schutz vor Endlos-Schleifen.

Sie sehen das auf dem Admin-Dashboard als gelbes Warn-Banner mit Link zu Settings.

Re-Aktivieren: Endpoint öffnen → Active-Toggle → Speichern. Nächste Events werden wieder versendet.

Delivery-History

Pro Endpoint zeigt PartnerDesk die letzten N Delivery-Versuche:

• HTTP-Status der Response.
• Response-Body-Auszug.
• Zeitpunkt.

Sinnvoll für Debugging: hat Ihr Endpoint überhaupt geantwortet?

Sentry-Integration

Bei finalem Aufgeben (alle Retries erschöpft) wird der Fehler in Sentry geloggt mit Tags tenant.slug und webhook.event — Plattform-Owner sieht das im Sentry-Dashboard.

Best Practices

Idempotenz

Jeder Webhook hat eine eindeutige Event-ID. Speichern Sie diese in Ihrem System — bei Duplikat (z. B. wenn ein vorheriger Webhook bei Ihnen erfolgreich ankam, aber unsere Response verloren ging) → ignorieren.

Schnelle Response

Antworten Sie innerhalb von 10 Sekunden (Timeout). Lange Verarbeitung → in eine eigene Queue verschieben + sofort 200 OK antworten.

Failsafe

Wenn Ihr Endpoint mehrere Tage offline ist: PartnerDesk hat keinen Buffer. Verlorene Events sind verloren. Bei kritischen Use-Cases zusätzlich täglich per API pollen.

Verwandte Kapitel

• 130 — Public-API (Lese-Variante)
• 37 — Custom Webhook (Inbound-Variante)
• 112 — Webhook-Event-Log (Inbound)
• 113 — Failed-Messages

---

Technische Tiefen-Doku: ../137-outgoing-webhooks.md, ../138-cursor-write-backoff.md, ../142-phase-21-webhook-tabs-blocks.md, ../148-lead-campaigns-bundle.md