Webhooks konfigurieren
July 30, 2026
Konfigurieren Sie FlowAlp Pay Webhooks: Dashboard-Setup, Content-Types, Retry-Plan, 20-Sekunden-Timeout, Idempotenz und sichere Bestellbestätigung.
Webhooks sind POST-Benachrichtigungen, die FlowAlp Pay an Ihr Backend sendet, sobald sich der Status einer Transaktion oder Subscription ändert; auch verarbeitete Auszahlungen lösen Benachrichtigungen aus. Sie sind der zuverlässige Weg, Bestellungen synchron zu halten — der Browser-Redirect nach dem Checkout ist es nicht.
Webhook im Dashboard anlegen
Melden Sie sich im Dashboard unter https://pay.flowalp.com an und öffnen Sie den Bereich Webhooks. Pro Webhook hinterlegen Sie:
- Eine öffentlich erreichbare HTTPS-URL (oder IP-Adresse), die die Daten empfängt und verarbeitet
- Ob fehlgeschlagene Zustellungen wiederholt werden sollen
- Den Content-Type des Payloads
| Content-Type | Header-Wert | Wann sinnvoll |
|---|---|---|
| JSON | application/json | Empfohlen für praktisch jeden Stack |
| Normal (PHP-Post) | application/x-www-form-urlencoded | Klassische Formular-Verarbeitung, z. B. direktes $_POST-Handling |
Wiederholungen und Timeout
Mit aktiviertem Retry wird die Zustellung bis zu 10-mal versucht, bis Ihr Endpoint erfolgreich antwortet:
| Versuch | Zeitpunkt |
|---|---|
| 1 | So bald wie möglich — höchstens 1 bis 1,5 Minuten nach dem ersten synchronen Versuch |
| 2 | 15 Minuten nach dem letzten Versuch |
| 3 | 1 Stunde nach dem letzten Versuch |
| 4 | 2 Stunden nach dem letzten Versuch |
| 5 | 4 Stunden nach dem letzten Versuch |
| 6–10 | Jeweils 24 Stunden nach dem letzten Versuch |
Ihr Endpoint muss innerhalb von 20 Sekunden antworten, sonst läuft die Anfrage in einen Timeout und das Log zeigt HTTP-Status 0 mit einer Timeout-Meldung. Antworten Sie sofort mit 200 und verlagern Sie schwere Arbeit in eine Queue.
Webhook-Einstellungen von Shop-Integrationen
Aktivieren Sie im Dashboard eine E-Commerce-Integration (zum Beispiel WooCommerce), registriert diese einen eigenen Webhook Richtung Shop und bringt eine eigene Retry-Option mit — Intervalle: 5 Minuten, 15 Minuten, 1 Stunde, 2 Stunden, 4 Stunden, danach alle 24 Stunden. Tragen Sie die Shop-URL exakt ein: Ein Schema-Fehler wie http:// statt https:// oder ein fehlendes Unterverzeichnis bricht die Webhook-Verarbeitung.
Checkout per Webhook bestätigen
- Erstellen Sie das Gateway und speichern Sie dessen ID zusammen mit Ihrer
referenceId. - Empfangen Sie den Webhook bei Statuswechsel — siehe Events und Payloads.
- Prüfen Sie die Signatur, bevor Sie irgendeinen Bestellstatus anfassen.
- Ordnen Sie das Event über
referenceId(oder die Payment-Link-ID in den Invoice-Daten) der erwarteten Bestellung zu. - Rufen Sie die Transaktion per API ab, wenn Ihr Risikomodell eine zweite Quelle verlangt.
- Erst dann markieren Sie die Bestellung als bezahlt und erfüllen sie.
Verwenden Sie den Browser-Redirect auf die Erfolgsseite nie als einzige Zahlungsbestätigung — Kundschaft kann den Browser mitten im Ablauf schliessen, und URLs lassen sich direkt aufrufen.
Korrekt antworten und idempotent bleiben
- Antworten Sie mit
2xxinnerhalb von 20 Sekunden; alles andere gilt als fehlgeschlagene Zustellung und löst — falls aktiviert — Wiederholungen aus. - Dasselbe Event kann mehrfach eintreffen — deduplizieren Sie über Transaktions-ID plus Status, bevor Sie handeln.
- Verarbeiten Sie Events asynchron und führen Sie ein Log über empfangene Payloads und Ergebnisse für Audits.
Sicherheits-Checkliste
- Exponieren Sie einen dedizierten Webhook-Endpoint, keine Allzweck-Route.
- Nur über HTTPS ausliefern.
- Webhook-Signaturen prüfen und ungültige mit einer Nicht-2xx-Antwort ablehnen.
- Keine Secrets oder vollständigen Payloads in allgemeine Anwendungslogs schreiben.
Nächster Schritt: Sehen Sie sich die Event-Typen und Payloads an und richten Sie danach die Signaturprüfung ein.