Webhooks verständlich: Wie Ihre Tools automatisch miteinander sprechen
Kurz gesagt: Ein Webhook ist eine Nachricht, die ein Dienst an eine Adresse von Ihnen schickt, sobald etwas passiert, etwa eine neue Bestellung. Ihr Tool muss nicht ständig nachfragen, denn der Dienst meldet das Ereignis selbst. Damit das zuverlässig läuft, prüfen Sie die Signatur jeder Nachricht, antworten schnell mit einem Erfolgscode und behandeln doppelte Zustellungen. Testen Sie zuerst mit einem Testdienst, bevor Sie echte Bestellungen weiterleiten, und protokollieren Sie jede Nachricht, damit Sie Fehler nachvollziehen können.
Der Unterschied zwischen Abfrage und Meldung
Stellen Sie sich einen Briefkasten vor. Bei einer Abfrage (API) gehen Sie jeden Morgen selbst zum Briefkasten und schauen nach. Bei einem Webhook klingelt der Zusteller und legt den Brief direkt auf Ihre Fußmatte. Die Abfrage ist sinnvoll, wenn Sie gezielt Daten holen. Der Webhook ist sinnvoll, wenn Sie sofort reagieren müssen, etwa auf eine Zahlung.
Ein Beispiel: Ein Onlineshop für Kosmetik möchte, dass nach jeder bezahlten Bestellung eine Nachricht im Teamchat erscheint und der Versandauftrag angelegt wird. Ohne Webhook müsste ein Programm alle fünf Minuten fragen, ob es neue Bestellungen gibt. Mit Webhook kommt die Nachricht im Moment der Zahlung.
So richten Sie einen Webhook ein
- Legen Sie eine Empfangsadresse an, die über HTTPS erreichbar ist. Sie ist eine Webadresse, die Daten annimmt, etwa ein Pfad mit dem Namen "bestellung" auf Ihrer eigenen Domain.
- Tragen Sie diese Adresse im Dienst ein, zum Beispiel im Shop, Zahlungsanbieter oder Formulartool, und wählen Sie nur die Ereignisse aus, die Sie brauchen.
- Der Dienst bekommt ein Geheimnis oder einen Schlüssel. Speichern Sie ihn außerhalb des Codes, zum Beispiel in den Einstellungen Ihres Hostings.
- Senden Sie einen Testevent aus dem Dienst und prüfen Sie, ob Ihre Adresse ihn annimmt.
Signaturen prüfen
Jeder Empfänger muss prüfen, ob eine Nachricht wirklich vom Dienst stammt. Viele Dienste senden dafür eine Signatur im Header mit, die mit dem Geheimnis berechnet wird. Ihr Empfänger rechnet dieselbe Signatur nach und verwirft Nachrichten, die nicht übereinstimmen. Fehlt diese Prüfung, kann jeder Ihre Adresse mit gefälschten Bestellungen füttern.
Der Anbieter beschreibt in seiner Dokumentation, wie die Prüfung im Detail funktioniert. Verwenden Sie dazu die Bibliotheken, die der Anbieter empfiehlt, statt eigene Verfahren zu bauen.
Wiederholungen und doppelte Nachrichten
Kommt keine Antwort mit Erfolgscode zurück, wiederholt der Dienst die Zustellung oft nach einer steigenden Wartezeit. Dadurch kann dieselbe Bestellung zweimal ankommen. Lösen Sie das so:
- Speichern Sie die Ereignis-Kennung jeder verarbeiteten Nachricht und überspringen Sie bekannte Kennungen.
- Antworten Sie innerhalb weniger Sekunden mit einem Erfolgscode und verarbeiten Sie längere Aufgaben danach.
- Legen Sie für jede Zustellung einen Protokolleintrag mit Zeitpunkt, Ereignis und Ergebnis an.
Praxistest mit einem Testdienst
Bevor Sie echte Daten weiterleiten, testen Sie mit einem Dienst, der Nachrichten an eine Testadresse schickt. Prüfen Sie folgende Punkte:
- Kommt die Nachricht vollständig an, mit allen Feldern?
- Wird eine gefälschte Nachricht ohne gültige Signatur abgelehnt?
- Erzeugt eine doppelte Zustellung keine doppelte Bestellung?
- Erscheint der Eintrag im Protokoll, auch wenn der Versand fehlschlägt?
Erst wenn alle Antworten Ja sind, schalten Sie den echten Kanal ein.
Ein vollständiges Beispiel
Eine Bestellung im Onlineshop löst ein Ereignis aus. Der Shop sendet eine Nachricht mit Bestellnummer, Produkten, Lieferadresse und Gesamtbetrag an Ihre Empfangsadresse. Der Empfänger prüft die Signatur, speichert die Ereignis-Kennung und antwortet mit einem Erfolgscode. Danach legt er einen Versandauftrag an und schickt eine Nachricht in den Teamchat. Schlägt der Versandauftrag fehl, bleibt das Ereignis im Protokoll mit Fehlermeldung, und jemand im Team sieht sie am selben Tag. Genau diesen Ablauf testen Sie, bevor echte Bestellungen fließen: einmal erfolgreich, einmal mit falscher Signatur, einmal als doppelte Zustellung.
Wann Webhooks nicht passen
Für Auswertungen über Monate sind Abfragen oft besser, weil Sie Daten gezielt holen und Zeiträume festlegen. Bietet ein Dienst keine Webhooks oder nur eingeschränkte Ereignisse, bleibt der Weg über die Schnittstelle mit regelmäßigen Abfragen. Auch bei hohem Volumen brauchen Sie eine Warteschlange zwischen Empfang und Verarbeitung, damit Ihr System nicht überlastet wird.
Typische Fehler im Alltag
Der häufigste Fehler ist eine Adresse, die nur im Testbetrieb funktioniert, weil dort eine Anmeldung fehlt oder ein anderer Schlüssel gilt. Ein zweiter Fehler entsteht bei der Signatur: Sie wird mit dem falschen Geheimnis berechnet, etwa weil am Ende ein Leerzeichen hängt. Prüfen Sie beides, bevor Sie den Kanal als fertig melden. Ein dritter Punkt betrifft die Uhrzeit. Viele Dienste lassen Nachrichten nur innerhalb eines Zeitfensters zu, und ein falsch eingestellter Server verwirft sie deshalb.
Häufige Fragen
Brauche ich dafür einen Entwickler?
Für eine einfache Weiterleitung nutzen viele Betriebe Automatisierungsdienste mit fertigen Bausteinen. Sobald Signaturprüfung, Wiederholungen oder eigene Logik nötig sind, lohnt sich eine Fachperson, die den Ablauf prüft.
Muss ich innerhalb einer bestimmten Zeit antworten?
Der Dienst erwartet eine Antwort innerhalb seiner Frist, die häufig nur wenige Sekunden beträgt. Wird sie überschritten, gilt die Zustellung als fehlgeschlagen und wird wiederholt. Lange Aufgaben verarbeiten Sie deshalb erst nach der Antwort, etwa über eine Warteschlange.
Wie speichere ich das Geheimnis sicher?
Legen Sie es in den Einstellungen Ihres Hostings ab, nicht im Quellcode und nicht in einer Datei im öffentlichen Ordner. Teilen Sie es nur mit den Personen, die den Empfänger betreiben, und tauschen Sie es aus, sobald jemand den Zugang verlässt.
Was passiert, wenn meine Adresse ausfällt?
Viele Dienste wiederholen die Zustellung eine Zeit lang und zeigen Fehler im Dashboard. Prüfen Sie diese Fehler regelmäßig, denn Nachrichten, die nie ankommen, fallen sonst niemandem auf.
Sind Webhooks sicher?
Sie sind so sicher wie ihre Prüfung. Ohne Signaturprüfung und ohne HTTPS sollten Sie keine echten Daten übertragen. Achten Sie außerdem darauf, welche Daten Sie speichern und wie lange.
Wie unterscheidet sich ein Webhook von einer Automatisierung?
Ein Webhook ist der Auslöser, die Automatisierung ist der Ablauf danach. Der Webhook liefert das Ereignis, die Automatisierung entscheidet, was damit geschieht.
Wenn Sie Ihre Shop-Bestellungen automatisch an Ihre Werkzeuge weitergeben möchten, besprechen wir gern mit Ihnen den passenden Weg: Gespräch anfragen.