Registrieren

Webhook

Transaktions- und Abonnement-Statusänderungen in Echtzeit empfangen.

Webhooks konfigurierst du in den Einstellungen deines zahls.ch-Händlerkontos. In der Navigation unter «Webhooks».

Konfiguration

  • Gib eine erreichbare URL bzw. IP-Adresse an, unter der du die Daten empfängst und verarbeitest
  • Lege fest, ob Webhooks bei einem Fehler auf deinem Verarbeitungsserver erneut gesendet werden sollen
  • Wähle zwischen zwei Inhaltstypen
    • Normal (PHP-Post): application/x-www-form-urlencoded
    • JSON: application/json – empfohlen für verschiedene Anwendungen

Wiederholung bei Fehler

Ist die Option aktiv, versucht die zahls.ch-Software, den Webhook bis zu 10-mal zu senden, bis eine erfolgreiche Antwort zurückkommt.

Die Versuche erfolgen in folgenden Abständen:

  1. Sofort (max. 1–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. 24 Stunden nach dem letzten Versuch
  7. 24 Stunden nach dem letzten Versuch
  8. 24 Stunden nach dem letzten Versuch
  9. 24 Stunden nach dem letzten Versuch
  10. 24 Stunden nach dem letzten Versuch

Timeout

Dein Server muss innerhalb von 20 Sekunden antworten, sonst läuft die Anfrage ab. Im Log erscheint HTTP-Status 0 und als Antworttext «Operation timed out after 20000 milliseconds with 0 bytes received».

Verwendung

Für eine Webshop-Integration erstellst du ein zahls.ch Gateway. Nach der Transaktion erhältst du eine Benachrichtigung auf deinen Server. Die Transaktion erkennst du an paymentLinkId oder referenceId im Invoice-Objekt.

Signatur

Zur Absicherung prüfst du jeden Webhook über die Signatur. Sie steht im HTTP-Header X-Webhook-Signatur und wird als hex-kodiertes SHA-256-HMAC (Kleinbuchstaben) aus dem unveränderten Request-Body und deinem Signing Key (UTF-8-String) berechnet.

Wichtige Implementierungsdetails

  • Signierte Daten: Nutze den rohen, unveränderten Request-Body. Serialisiere geparstes JSON nicht erneut.
  • Key-Kodierung: Der Signing Key wird als UTF-8-Plaintext verwendet, nicht Base64-dekodiert.
  • Signatur-Kodierung: Das HMAC-Ergebnis ist hex-kodiert (Kleinbuchstaben), nicht Base64.

Daten

Die Daten werden als JSON oder als HTTP-POST-Formulardaten gesendet. In dieser Dokumentation wird JSON verwendet.

Sofern nicht anders angegeben, sind Beträge in der kleinsten Währungseinheit angegeben. Beispiel: 200 entspricht CHF 2.00.

Beispiele

Derzeit liegt nur ein Beispiel in PHP vor.

Vollständiges PHP-Beispiel mit passender MySQL-Datenbank: hier herunterladen.

Verwandte Themen