Einleitung
Webhooks sind das Rückgrat moderner Integrationen: Sie treiben Echtzeit‑Automatisierung an, reduzieren manuelle Arbeit und verbessern Transparenz zwischen Händlern, Partnern und Abrechnungssystemen. Für Betreiber von Partnerprogrammen ist die zuverlässige Synchronisation von Conversion‑Events, Auszahlungsvorbereitung und Auszahlungsausführung besonders kritisch. Dieser Beitrag zeigt praxisnahe Webhook‑Workflows mit Affilentra — inklusive Payload‑Templates und Integrationshinweisen für Buchhaltungssysteme, Payment‑Provider und interne ERP‑Systeme.
Warum Webhooks mit Affilentra?
Affilentra bietet eine self‑hosted Affiliate‑Plattform mit klar getrennten Rollen (Softwarebetreiber, Händler, Partner). Webhooks erlauben hier, Ereignisse aus dem Partnerprogramm automatisiert an externe Systeme zu liefern: Validierte Conversions, vorbereitete Auszahlungslisten und Statusupdates. Durch die self‑hosted Architektur behalten Händler die Datenhoheit und können Webhook‑Endpunkte selbst betreiben oder in bestehende Middleware einbinden.
Wesentliche Eventtypen und ihre Verwendung
Die folgenden Events bilden die Grundlage für praxisnahe Workflows:
- conversion.created – ein Tracking‑Event wurde registriert und validiert.
- conversion.updated – Statusänderungen (z. B. chargeback, refund, bestätigte Conversion).
- payout.prepared – eine Auszahlungsliste bzw. Auszahlungseintrag wurde für die Abrechnung erstellt.
- payout.paid – Auszahlung wurde an den Payment‑Provider übermittelt bzw. als ausgezahlt markiert.
- accounting.export_ready – Buchhaltungsrelevante Daten stehen zum Export bereit (z. B. als Buchungssatz oder CSV).
- erp.update_required – Statusänderung, die im internen ERP System nachgeführt werden muss (z. B. Fulfillment‑ oder Rechnungsstatus).
Payload‑Templates (Beispiele)
Die folgenden Payloads sind als Vorlagen für die Integration gedacht. Passen Sie Felder an Ihr internes Schema an und verarbeiten Sie nur die Felder, die Sie benötigen.
conversion.created (Beispiel)
{
"event": "conversion.created",
"timestamp": "2026-11-04T10:15:30Z",
"conversion": {
"id": "conv_12345",
"merchant_id": "m_987",
"partner_id": "p_456",
"offer_id": "o_22",
"amount": 149.90,
"currency": "EUR",
"status": "pending_validation",
"meta": { "order_ref": "ORD-20261104-001" }
}
}
payout.prepared (Beispiel)
{
"event": "payout.prepared",
"timestamp": "2026-11-04T11:00:00Z",
"payout": {
"id": "po_20261104_01",
"merchant_id": "m_987",
"partner_id": "p_456",
"gross_amount": 320.00,
"fees": 5.00,
"net_amount": 315.00,
"currency": "EUR",
"payout_method": "bank_transfer",
"batch_id": "batch_20261104",
"entries": [ { "conversion_id": "conv_12345", "amount": 120.00 }, { "conversion_id": "conv_12346", "amount": 200.00 } ]
}
}
payout.paid (Beispiel)
{
"event": "payout.paid",
"timestamp": "2026-11-04T12:30:00Z",
"payout": {
"id": "po_20261104_01",
"paid_at": "2026-11-04T12:28:00Z",
"transaction_id": "txn_7890",
"provider_status": "settled"
}
}
accounting.export_ready (Beispiel)
{
"event": "accounting.export_ready",
"timestamp": "2026-11-04T12:35:00Z",
"export": {
"id": "exp_20261104_01",
"format": "csv",
"records": [ { "account_code": "8400", "debit": 0, "credit": 315.00, "description": "Affiliate Payout" } ]
}
}
Typische Integrationsworkflows
1) Conversion → Buchhaltungsvorbereitung
Workflow: conversion.created → conversion.updated (bestätigt) → accounting.export_ready.
- Bei conversion.created: Store minimalen Datensatz in der Middleware, führen Sie Validierungen durch (z. B. Duplikate, CVR/Order‑Referenzen).
- Bei conversion.updated mit Status confirmed: Erzeuge Buchungseintrag (Debitor, Erlös, MwSt) oder markiere Conversion zur Aufnahme in den nächsten Export.
- Bei accounting.export_ready: Generiere CSV/DATEV/JSON und lege sie in das Buchhaltungsverzeichnis oder sende sie per SFTP an Ihren Steuerberater.
2) Auszahlungsvorbereitung → Payment‑Provider
Workflow: payout.prepared → Payment‑Provider API → payout.paid.
- payout.prepared: Erzeuge Batch mit Payout‑Einträgen, prüfe Limits und Verfügbarkeit (Guthaben, KYC‑Status).
- Sende Batch an Ihren Payment‑Provider; verwende idempotente Aufrufe und liefere batch_id als Referenz.
- Empfange Rückmeldung vom Provider, markiere Transaktionen und warte auf payout.paid Event zur endgültigen Buchung.
3) ERP‑Synchronisation für Fulfillment und Rechnungsstatus
Workflow: conversion.updated / erp.update_required → ERP API.
- Bei Statusänderungen (z. B. fulfilled, refunded) sendet Affilentra ein erp.update_required Event.
- Mapping: external_reference → ERP Auftragsnummer; aktualisiere Fulfillment‑Status, Rechnungsnummern und Zahlstatus.
- Best Practices: Verwenden Sie Batch‑Ack, Rate‑Limitierung und prüfen Sie Referenzen auf Eindeutigkeit.
Best‑Practices für robuste Integrationen
- Sicherheit: Signieren Sie Webhook‑Payloads mit HMAC (SHA256) und prüfen Sie Timestamps, um Replay‑Angriffe zu verhindern.
- Idempotenz: Verarbeiten Sie dieselbe Event‑ID mehrfach ohne Nebeneffekte. Verwenden Sie dedizierte Idempotenz‑Keys.
- Fehlerbehandlung: Implementieren Sie Retry‑Logik mit Exponential Backoff; loggen Sie fehlgeschlagene Deliveries zentral.
- Versionierung: Führen Sie ein Event‑Schema‑Versionfeld ein, um Schema‑Änderungen kompatibel zu halten.
- Batching: Senden Sie für Buchhaltung und Payouts aggregierte Events (z. B. batch_id), um Aufwand und Latenz zu reduzieren.
- Nutzdatenminimierung: Senden Sie nur die Felder, die Zielsysteme benötigen; lagern Sie zusätzliche Metadaten optional aus.
- Monitoring: Überwachen Sie Delivery‑Rates, Latenz und Fehlerquote; benachrichtigen Sie Verantwortliche bei Ausfällen.
Rollenorientierte Hinweise
- Händler (Merchant): Legen Sie Webhook‑Endpoints fest, wählen Sie Events und definieren Sie Payout‑Methoden. Self‑hosting ermöglicht vollständige Kontrolle über Datenflüsse.
- Partner (Publisher): Profitieren Sie von nachvollziehbaren Trackinglinks und transparenten Auszahlungsstatusmeldungen, die über Webhooks an dashboards oder Buchhaltungstools geliefert werden können.
- Softwarebetreiber: Stellen Sie sichere Signaturen, Dokumentation und Monitoring bereit; bieten Sie Vorlagen und Mapping‑Beispiele für gängige Buchhaltungs‑ bzw. Zahlungsanbieter an.
Praxisbeispiele: Implementierungsschritte
- Definieren Sie die relevanten Events und ein minimal benötigtes Feldset (z. B. conversion_id, amount, currency).
- Richten Sie eine Middleware oder ein kleines Empfangs‑Service ein, das Webhooks validiert, dedupliziert und an Zielsysteme routet.
- Implementieren Sie HMAC‑Signaturen und prüfen Sie Timestamps innerhalb eines kurzen Fensters (z. B. 5 Minuten).
- Testen Sie mit simulierten Events: conversion.created → payout.prepared → payout.paid → accounting.export_ready.
- Dokumentieren Sie Fehlercodes und Recovery‑Prozesse für Ihre Finance‑ und Operate‑Teams.
Fazit und nächster Schritt
Mit Affilentra lassen sich Webhook‑Workflows für Conversion‑Tracking, Auszahlungsvorbereitung und Buchhaltungs‑Exporte praxistauglich und sicher abbilden — speziell in self‑hosted Szenarien, in denen Kontrolle und Datenschutz zentral sind. Die Kombination aus klaren Event‑Schemas, idempotenter Verarbeitung und kontrollierten Payout‑Batches reduziert manuellen Aufwand und erhöht Transparenz für Händler und Partner.
Bereit, Webhooks produktiv zu nutzen? Einstieg wählen
Nächster Schritt
Affilentra selbst ausprobieren
Einheitliche Plattform, die Produktbereitstellung, Tracking, Conversion-Validierung, Provisionsberechnung und Auszahlung entlang klar getrennter Rollen transparent zusammenführt; Option zur self-hosted Installation mit Dauerlizenz ohne Umsatzbeteiligung; Händler behalten Kontrolle über Produkte, Konditionen und Werbemittel; Partner erhalten persönliche Trackinglinks und nachvollziehbare Auszahlungshistorie.