30 — Webhook-Übersicht

PartnerDesk verarbeitet Sales-Events von externen Zahlungsanbietern über Webhooks — HTTP-Calls, die der Provider bei jedem Ereignis (Sale, Refund, Subscription-Update) an PartnerDesk schickt.

Unterstützte Provider

Provider	Webhook-URL	Authentifizierung	Doku
Stripe	/api/webhooks/{slug}/stripe	HMAC-SHA256 (Stripe-Signature)	31
Digistore24	/api/webhooks/{slug}/digistore24	HMAC-SHA512	32
CopeCart	/api/webhooks/{slug}/copecart	HMAC-SHA256 (JSON oder Form)	33
Ablefy	/api/webhooks/{slug}/ablefy	HMAC-SHA256, 3 mögliche Header	34
easybill	/api/webhooks/{slug}/easybill	Token-basiert	35
lexoffice	/api/webhooks/{slug}/lexoffice	Bearer-Token	36
Custom (Zapier, Make, n8n, eigene Systeme)	/api/webhooks/{slug}/custom	HMAC-SHA256, eigenes JSON-Schema	37

{slug} ist Ihr Tenant-Slug (z. B. 4leads).

Setup-Workflow

Für jeden Provider gleichermaßen:

1. PartnerDesk öffnen: Admin → „Zahlungsanbieter" → gewünschten Provider auswählen.
2. Webhook-URL kopieren — PartnerDesk zeigt Ihnen die fertige URL für Ihren Tenant an.
3. Im Provider eintragen — beim Provider unter „Webhooks" / „Notifications" die URL hinzufügen.
4. Secret zurück nach PartnerDesk — der Provider zeigt Ihnen ein Webhook-Secret. Tragen Sie es im Admin-Portal ein.
5. Speichern → Status-Badge wechselt auf „Aktiv".

Bei manchen Providern (lexoffice, easybill) brauchen Sie zusätzlich einen API-Key für ausgehende Calls (z. B. Gutschrift-Anlage). Siehe Provider-Doku.

Was passiert bei einem eingehenden Webhook?

Provider ─→ POST /api/webhooks/{slug}/{provider}
              │
              ▼
       ┌─────────────────────────┐
       │ 1. Tenant auflösen      │
       │ 2. Provider-Config laden│
       │ 3. Signatur prüfen      │
       └────────────┬────────────┘
                    │
                    ▼
       ┌─────────────────────────┐
       │ 4. Provider-Handler     │
       │   (Stripe/Digistore/...)│
       └────────────┬────────────┘
                    │
                    ▼
       ┌─────────────────────────┐
       │ 5. Partner auflösen     │
       │   (5-stufig)            │
       └────────────┬────────────┘
                    │
                    ▼
       ┌─────────────────────────┐
       │ 6. Transaction anlegen  │
       │   + MLM-Provisionen     │
       └────────────┬────────────┘
                    │
                    ▼
       ┌─────────────────────────┐
       │ 7. WebhookEvent loggen  │
       │   (für Audit)           │
       └─────────────────────────┘

Event-Typen (Übersicht)

Alle Provider unterstützen ein ähnliches Set:

Event	Effekt
Payment / Sale	Neue Transaktion + MLM-Provisionen
Rebill / Subscription Charge	Folge-Transaktion (isRecurring=true, recurringNumber=N)
Refund	Bestehende Transaktion auf refunded
Chargeback	Bestehende Transaktion auf clawback

Provider-spezifische Events werden in den einzelnen Doku-Kapiteln beschrieben.

Idempotenz

PartnerDesk verarbeitet jeden Webhook idempotent: ein zweiter Webhook mit derselben (provider, external_transaction_id)-Kombination wird erkannt und übersprungen (skipped). Das ist wichtig, weil Provider bei vermeintlichen Timeouts den Webhook wiederholen.

Webhook-Event-Log

Jeder eingehende Webhook wird vollständig protokolliert:

• Payload (Body).
• Signatur-Validität.
• Verarbeitungszeit in ms.
• Resultat (success, skipped, failure, invalid_signature).

Admin-Portal → „Webhook-Log" (tenant-scoped). Plattform-Admin sieht alle Tenants.

Details: 112 — Webhook-Event-Log.

Replay

Bei failure oder skipped-Webhooks (z. B. Provider hatte fehlerhafte Daten gesendet, später korrigiert) kann der Webhook manuell neu verarbeitet werden — Klick auf „Replay" im Detail-Modal. Signaturprüfung wird beim Replay übersprungen, aber ein neuer Audit-Eintrag mit Referenz zur ursprünglichen ID wird erstellt.

Rate-Limits

Pro Tenant + Provider: 120 Webhooks/Minute (sliding window). Schutz gegen Provider-Storms bei Migrations- oder Test-Szenarien.

Bei Überschreitung: HTTP 429 mit Retry-After-Header. Provider versuchen üblicherweise automatisch erneut.

Verwandte Kapitel

• 31 bis 37 — Provider-spezifische Setups.
• 50 — Wie Tracking-Cookies die Partner-Auflösung beeinflussen.
• 112 — Webhook-Event-Log inspizieren.

---

Technische Tiefen-Doku: ../001-initial-setup.md (Webhook-Subsystem), ../025-webhook-audit-log.md, ../058-unified-tracking.md (PartnerResolver)