Webhooks

Was ist ein Webhook?

Ein Webhook erlaubt einer Anwendung, mit einer anderen Anwendung zu kommunizieren und ihr Informationen in Echtzeit zur Verfügung zu stellen. Beispielsweise kann Anwendung A eine Benachrichtigung an Anwendung B senden, wenn ein bestimmtes Ereignis eintritt.

Bezogen auf zahls.ch können mit Webhooks beispielsweise Transaktionen und deren Status mit Drittsystemen wie einem E-Commerce-System oder einer Content Management Software synchronisiert werden.

Erstellen eines Webhooks

Um einen Webhook zu erstellen, logge dich in dein Konto bei zahls.ch ein und navigiere im Hauptmenü der Dashboard zu Webhooks.

Klicke danach auf auf die weisse Schaltfläche "Webhook erstellen", worauf sich das folgenden Fenster öffnet:

1. Name: Vergib für den Webhook einen beliebigen Namen. Dieser dient lediglich dazu, dass du den Webhook einfacher identifizieren kannst, falls du mehrere Webhooks anlegst.
2. Webhook-URL: Trage die URL ein, an die der Webhook gesendet werden soll. Stelle dabei sicher, dass die URL exakt stimmt. Bei einer Integration erhältst du die einzutragende URL häufig vom anzubindenden Drittsystem.
3. Webhook-Inhaltstyp: Wähle, ob für die Kommunikation zwischen zahls.ch und dem Drittsystem das Format "PHP-Post" oder das Format "JSON" angewendet werden soll.
4. Webhook-Version: Wähle die korrekte Version des Webhooks aus. du findest diese Information in der Anleitung zur Anbindung der jeweiligen E-Commerce-Systems, CMS- oder Unternehmenssoftware-Tools.
5. Bei Fehler erneut versuchen: Es kann vorkommen, dass der Webhook unter der Webhook-URL einen Fehler auslöst. Durch Aktivierung dieses Kontrollkästchens stellst du sicher, dass er in so einem Fall erneut ausgelöst wird. Der Versuch, den Webhook zu versenden, wird dann bis zu 10 Mal wiederholt.

6. Ereignisse: Definiere, bei welchem Ereignis beziehungsweise bei welchen Ereignissen der Webhook ausgelöst werden soll. Es stehen die Typen "Transaction", "Subscription" und "Payout" zur Verfügung. Weitere Informationen findest du im Kapitel "Typen von Webhooks".
7. Link zur Integration: Wähle entweder eine bestehende Integration (einen konkreten API-Schlüssel) aus, damit der Webhook nur für Ereignisse in Zusammenhang mit diesem API-Schlüssel angewendet wird. Oder wähle die Option "Keine Integration (alle Ereignisse)", um den Webhook in jedem Fall auszuführen.
8. Abschliessen: Klicke auf "Hinzufügen", um die Konfiguration abzuschliessen und den Webhook zu erstellen.

Sicherheit von Webhooks

Für jeden Webhook, den du im Dashboard anlegst, erstellt zahls.ch automatisch eine individuelle Signatur (Secret), die bei jeder Webhook-Anfrage mitgesendet wird. So kann das empfangende System prüfen, ob die Anfrage wirklich von zahls.ch stammt und nicht unterwegs manipuliert wurde. Das erhöht die Sicherheit bei der Weiterverarbeitung von Zahlungs- und Statusinformationen.

Weitere Informationen findest du in unserer Entwickler-Dokumentation.

Typen von Webhooks

In zahls.ch gibt es die folgenden drei Arten von Webhooks:

Übersicht über erstellte Webhooks

Falls du in zahls.ch bereits Webhooks erstellt hast, findest du sie, wenn du im Hauptmenü deines Dashboards auf Webhooks klickst.

Webhook-Fehler

Bei der Kommunikation von zwei Systemen über Webhooks kann es zu Fehlern kommen. Solche Webhook-Fehler treten typischerweise auf, wenn das Zielsystem eine Anfrage ablehnt oder die Verarbeitung des Webhooks im Zielsystem einen Fehler auslöst.

Die Ursache von Webhook-Fehlern liegt in der Regel beim Zielsystem. Es kann aber auch sein, sie auf einer fehlerhaften Webhook-URL oder einem falschen Webhook-Inhaltstyps basieren.

Im folgenden Abschnitt zeigen wir dir Lösungen für die häufigsten Webhook-Fehler auf.

Webhook-Fehler bei Plugins

Für die Integration von zahls.ch in verschiedene E-Commerce-Systeme stehen Plugins zur Verfügung. Kommt es bei einer dieser Integrationen zu Webhook-Fehlern, empfehlen wir das folgende Vorgehen:

1. Lies die Dokumentation der jeweiligen E-Commerce-Integration sorgfältig durch und beachte dabei insbesondere die Angaben im Kapitel "Konfiguration von zahls.ch".
2. Stelle sicher, dass die eingetragene Webhook-URL korrekt ist. Ein häufiger Fehler ist, dass die Schreibweise der eingetragenen Webhook-URL nicht mit jener des Zielsystems übereinstimmt. Beispiel: https://meine-verkaufsseite.com/zahls-webhook versus https://**www.**meine-verkaufsseite.com/zahls-webhook

Falls du den Fehler nicht finden kannst, erstelle ein Support-Ticket und lass uns die folgenden Informationen zukommen:

• Instanzname in zahls.ch
• Webhook-URL
• Zugangsdaten zum Administrationsbereich deines Drittsystems

Fehler bei eigenen Webhooks

Falls du die Integration nicht über ein Plugin, sondern über einen manuell angelegten Webhook vorgenommen hast, raten wir dir, bei Webhook-Fehlern die Logs zu durchsuchen.

• Navigiere hierfür zu Webhooks und klicke neben dem betreffenden Webhook auf "Logs".

• Danach klickst du in der Liste der Webhook-Anfragen auf den Eintrag, den du untersuchen möchtest.

• Auf der rechten Seite des Bildschirms werden dir nun sämtliche Details zur entsprechenden Webhook-Anfrage angezeigt.

In den Details der Webhook-Anfrage werden unter anderem die folgenden Informationen angezeigt:

• psp: der Zahlungsanbieter, über den die Transaktion generiert wurde (z. B. Native_PSP für Payrexx Pay)

• uuid: die Transaktions-ID aus zahls.ch

Wenn du nach unten scrollst, findest du den HTTP-Status der Webhook-Anfrage.

Der HTTP-Status ist eine Antwort vom Zielserver, die in Form eines Zahlencodes an den Sender des Webhooks (in unserem Fall zahls.ch) zurückgegeben wird. Mithilfe des zurückgegebenen Wertes kannst du herausfinden, worin das Problem besteht und wie es behoben werden kann:

Webhook-Fehler mit HTTP-Status 0

Ein Webhook-Fehler mit HTTP-Status 0 tritt normalerweise auf, wenn der Zielserver (Webhook-URL) nicht innerhalb von 20 Sekunden eine Antwort auf die Anfrage von zahls.ch sendet.

Lösungsansätze:

• Bitte deinen technischen Spezialisten darum, die Performance deines Servers zu optimieren.
• Aktiviere beim Webhook in zahls.ch die Option “Bei Fehler erneut versuchen”, damit die Anfrage im Falle eines fehlgeschlagenen Webhooks erneut gesendet wird.

Webhook-Fehler mit HTTP-Status 301

Ein Webhook-Fehler mit HTTP-Status 301 tritt normalerweise auf, wenn eine Seite dauerhaft an einen neuen Ort verschoben wurde. Dies ist typischerweise der Fall, wenn der Domainname oder die URL-Struktur einer Webseite geändert wurde.

Lösungsansätze:

• Falls du diesbezüglich entsprechende Änderungen vorgenommen hast, müsstest du diese auch in zahls.ch entsprechend aktualisieren, damit die Webhooks wieder gesendet/beantwortet werden können.
• Lösche den Cache deines Browsers und versuche es nochmals.

Webhook-Fehler mit HTTP-Status 302

Ein Webhook-Fehler mit HTTP-Status 302 tritt normalerweise auf, wenn der Händler-Server, an den zahls.ch den Webhook sendet, zeitweise nicht erreichbar ist.

Lösungsansätze:

• Bitte deinen technischen Kontakt, zu prüfen, ob der Webhook korrekt eingerichtet ist.
• Bitte deinen technischen Kontakt, zu prüfen, woran die eingeschränkte Erreichbarkeit des Servers liegen könnte.

Webhook-Fehler mit HTTP-Status 403

Ein Webhook-Fehler mit HTTP-Status 403 tritt normalerweise auf, wenn sich unter der im Webhook angegebenen URL kein Shop befindet. Ein weiterer Grund kann sein, dass keine Erlaubnis für die Ausführung des Webhooks vorhanden ist.

Lösungsansätze:

• Stelle sicher, dass die im Webhook erfasste URL wirklich auf den Shop verweist.
• Bitte deinen Server-Dienstleister darum, die IP-Adressen des Webhooks (3.79.212.4, 3.73.29.220) zu whitelisten und so die Erlaubnis zur Ausführung des Webhooks zu erteilen.

Webhook-Fehler mit HTTP-Status 404

Ein Webhook-Fehler mit HTTP-Status 404 tritt normalerweise auf, wenn die vom Webhook angeforderte Ressource auf dem Server des Händlers nicht gefunden werden kann. Dies kann folgende Gründe haben:

• Die im Webhook angegebene URL ist falsch.
• Die im Webhook angegebene URL wurde gelöscht oder verschoben.
• Die Transaktion, auf die sich der gesendete Webhook bezieht, ist auf dem Server des Händlers nicht mehr vorhanden.

Lösungsansätze:

• Überprüfe, ob die im Webhook erfasste URL immer noch korrekt ist.
• Falls die Bestellung nicht mehr vorhanden ist, ignoriere den Webhook-Fehler.

Webhook-Fehler mit HTTP-Status 500

Ein Webhook-Fehler mit HTTP-Status 500 tritt normalerweise auf, wenn der Server des Händlers keine gültige Antwort auf die von zahls.ch gesendete Anfrage gibt. Dies kann folgende Ursachen haben:

• Die in zahls.ch hinterlegte URL zum Server des Händlers ist falsch.
• Der Server nimmt den Webhook zwar an, scheitert aber bei der Verarbeitung der Daten. In diesem Fall solltest du die Log-Files deines Servers prüfen, um an weitere Informationen zu gelangen.
• Der Server des Händlers war zum besagten Zeitpunkt vorübergehend nicht erreichbar.
• Der Fehler basiert auf einem falschen Format (JSON/Post Form Data)

Lösungsansätze:

• Prüfe die URL, die du beim Webhook in zahls.ch hinterlegt hast.
• Prüfe mit deinen Spezialisten die Erreichbarkeit deines Servers.
• Ändere das Format des Webhooks (JSON/Post Form Data) und versuche es erneut.

Falls du den Fehler nicht finden kannst, erstelle ein Support-Ticket und lass uns die folgenden Informationen zukommen:

• Instanzname in zahls.ch
• Webhook-URL
• Zugangsdaten zum Administrationsbereich deines Drittsystems

Verifizieren von Webhooks

Um Webhook-Aufrufe zu verifizieren, kannst du jeder Transaktion eine referenceId mitgeben.

Zur Verifizierung des Webhooks stehen zwei Möglichkeiten zur Verfügung:

• Signatur (Best Practice): Nutze einen individuellen Signaturschlüssel pro Webhook, um die Integrität der Daten mittels einer inhaltsbasierten Signatur zu validieren.
• API-Abgleich: Alternativ kann dein System den Transaktionsstatus manuell über die zahls.ch-API abgleichen, um die Authentizität zu bestätigen.

Weitere Informationen findest du in unserer Entwickler-Dokumentation.

Informationen für Entwickler

Zusätzliche technische Informationen zu Webhooks findest du im Artikel Webhook in unserer Entwickler-Dokumentation.