Webhook: Funktionsweise, Test und Sicherheit
· DigifyNow
Ein Webhook ist eine URL, die Sie bei einem Dienst hinterlegen. Tritt dort ein Ereignis ein, etwa eine bezahlte Rechnung, schickt der Dienst sofort einen HTTP-POST mit den Daten als JSON an diese URL. Ihr Empfänger prüft die Signatur, antwortet schnell mit einem 2xx-Statuscode und verarbeitet die Daten erst danach. Bleibt diese Antwort aus, schickt der Absender die Meldung erneut. Deshalb muss der Empfänger doppelte Meldungen erkennen.
Was ist ein Webhook?
Ein Webhook ist eine automatische Benachrichtigung von einem System an ein anderes. Das empfangende System stellt eine Adresse bereit, den sogenannten Webhook-Endpunkt. Diese Adresse tragen Sie beim sendenden Dienst ein und legen fest, bei welchen Ereignissen er sich melden soll. Danach muss Ihr System nicht mehr nachfragen. Der Dienst meldet sich von selbst, sobald etwas passiert. Fachleute nennen das Push statt Pull.
Ein konkretes Beispiel: Ein Kunde bezahlt online per Stripe. Stripe erzeugt intern das Ereignis „Zahlung erfolgreich“ und schickt eine HTTP-Anfrage mit der Methode POST an die hinterlegte URL. Im Inhalt der Anfrage, der Payload, steht ein JSON-Objekt mit Ereignistyp, Betrag, Kundennummer und einer eindeutigen Ereignis-ID. Ihr Empfänger liest das, legt im CRM den Zahlungseingang an und stößt den Rechnungsversand an. Niemand muss dafür das Zahlungs-Dashboard öffnen. Wichtig ist: Ein Webhook transportiert nur die Meldung. Alles danach, also Prüfen, Speichern und Weiterleiten, erledigt der Empfänger selbst.
Wofür nutzen Unternehmen Webhooks?
Webhooks passen überall dort, wo ein System ein anderes über ein einzelnes, klar benennbares Ereignis informieren soll. Typische Fälle im Mittelstand:
- Zahlung eingegangen: Der Zahlungsdienst meldet den Eingang, und die Buchhaltung oder das CRM setzt den Vorgang auf „bezahlt“.
- Formular abgeschickt: Die Website meldet eine neue Anfrage, und im CRM entsteht daraus sofort ein Kontakt mit Wiedervorlage.
- Code geändert: GitHub meldet einen Push, und ein Build- oder Deploy-Prozess startet.
- Nachricht eingegangen: Ein Messenger- oder Ticketsystem meldet eine neue Nachricht an einen Automatisierungsablauf.
- Statusmeldung an das Team: Ein internes System schreibt bei Fehlern automatisch in einen Chat-Kanal.
Bei wenigen Ereignissen am Tag, die ohnehin jemand von Hand bearbeitet, lohnt sich der Aufbau oft nicht. Dasselbe gilt, wenn der sendende Dienst gar keine Webhooks anbietet. Dann bleibt nur die regelmäßige Abfrage über eine Schnittstelle. Welche Abläufe sich generell für eine Automatisierung eignen, beschreibt unser Beitrag Prozesse automatisieren im KMU.
Wie funktioniert ein Webhook?
Technisch läuft jede Webhook-Zustellung in denselben Schritten ab, egal ob der Absender ein Zahlungsdienst, ein Shop oder ein Code-Repository ist:
- Registrieren: Sie hinterlegen beim Absender die Endpunkt-URL (immer mit https) und wählen die Ereignistypen aus. Meist erhalten Sie dabei ein gemeinsames Geheimnis, das Signing Secret.
- Ereignis tritt ein: Beim Absender passiert etwas, zum Beispiel eine Zahlung, eine Bestellung oder ein Push.
- Zustellung: Der Absender schickt einen HTTP-POST an Ihre URL. Im Header steht eine Signatur, im Body das Ereignis als JSON.
- Prüfen: Ihr Endpunkt berechnet die Signatur mit dem Secret selbst nach und verwirft die Anfrage, wenn die Werte nicht übereinstimmen.
- Bestätigen: Der Endpunkt antwortet mit einem Erfolgs-Statuscode aus dem 2xx-Bereich. Das geschieht, bevor eine lange Verarbeitung beginnt.
- Verarbeiten: Erst danach läuft die eigentliche Arbeit, am besten über eine Warteschlange. So können langsame Folgesysteme die Antwort nicht verzögern.
- Wiederholen: Kommt keine Erfolgsantwort, gilt die Zustellung als gescheitert. Viele Anbieter versuchen es dann nach einem festen Zeitplan erneut.
Was ist der Unterschied zwischen einem Webhook und einer API?
Eine API ist eine Schnittstelle, die Sie aktiv aufrufen: Sie fragen, und das System antwortet. Bei einem Webhook läuft es umgekehrt. Das andere System ruft Sie auf, sobald etwas passiert. Ein Webhook ersetzt die API also nicht, sondern ergänzt sie. Oft enthält die Meldung nur die Ereignis-ID, und die vollständigen Daten holt Ihr System danach über die API. Wie Endpunkte, Methoden und Tokens bei einer Schnittstelle zusammenspielen, erklärt unser Artikel API-Schnittstelle: Definition, Beispiel, Praxis.
| Verfahren | Wer startet die Kommunikation? | Wann kommen neue Daten an? | Wo es an Grenzen stößt |
|---|---|---|---|
| Polling über API | Ihr System fragt in festen Abständen nach | Erst bei der nächsten Abfrage | Viele Abfragen bringen keine neuen Daten, und Änderungen zwischen zwei Abfragen kommen verzögert an |
| Webhook | Der Absender meldet sich bei jedem Ereignis | Kurz nach dem Ereignis | Ihr Endpunkt muss öffentlich erreichbar sein. Ist er zu lange ausgefallen, gehen Meldungen nach dem letzten Wiederholungsversuch verloren. |
| WebSocket | Beide Seiten halten eine dauerhafte Verbindung offen | Laufend, in beide Richtungen | Die Verbindung muss ständig gehalten werden. Für einzelne Geschäftsereignisse zwischen zwei Servern ist das meist mehr Aufwand als nötig. |
Sind Webhooks sicher?
Eine Webhook-URL ist öffentlich erreichbar. Wer sie kennt, kann also Anfragen dorthin schicken. Wie sicher ein Webhook ist, hängt deshalb davon ab, was der Empfänger prüft, und nicht vom Verfahren selbst. Die großen Anbieter signieren ihre Meldungen. Stripe setzt einen Header Stripe-Signature mit Zeitstempel und einer HMAC-Signatur auf Basis von SHA-256 und beschreibt die Prüfung in seiner Webhook-Dokumentation. GitHub verschickt eine Signatur im Header X-Hub-Signature-256, nachzulesen in der GitHub-Dokumentation.
- Signatur prüfen: Den Wert über den unveränderten Rohtext der Anfrage berechnen. Wer das JSON vorher einliest und neu serialisiert, verändert die Bytes, und die Prüfung schlägt fehl.
- Zeitkonstant vergleichen: Für den Vergleich eine Funktion nutzen, die immer gleich lange braucht. Sonst lässt sich die Signatur über Zeitmessung schrittweise erraten.
- Zeitstempel prüfen: Ältere Meldungen verwerfen. Dann lässt sich eine abgefangene Anfrage nicht später noch einmal einspielen.
- Secret schützen: Das Signing Secret gehört in eine Umgebungsvariable oder einen Tresor, nicht in den Quellcode.
- Nur HTTPS: Ohne Verschlüsselung lassen sich Payload und Header unterwegs mitlesen.
- Daten nicht blind übernehmen: Eine Meldung wie „Bestellung bezahlt“ vor der Freigabe einer Lieferung per API gegenprüfen.
Was bei Webhooks schiefgeht
Die meisten Probleme mit Webhooks zeigen sich nicht beim ersten Test, sondern erst im laufenden Betrieb. Die typischen Fehler und ihre Ursachen:
- Doppelte Verarbeitung: Der Endpunkt hat die Meldung verarbeitet, aber zu spät geantwortet, und der Absender schickt sie erneut. Abhilfe schafft Idempotenz. Speichern Sie die Ereignis-ID und überspringen Sie jede ID, die schon verarbeitet wurde.
- Zeitüberschreitung: Der Endpunkt erstellt erst ein PDF, schreibt ins ERP und antwortet dann. Besser: sofort bestätigen und die Arbeit in eine Warteschlange legen.
- Falsche Reihenfolge: „Bestellung storniert“ kommt vor „Bestellung angelegt“ an. Für die Reihenfolge gibt es keine Garantie. Der Empfänger muss den Zeitstempel oder den aktuellen Stand per API prüfen.
- Stille Ausfälle: Der Server war nachts nicht erreichbar, und nach dem letzten Wiederholungsversuch gibt der Absender auf. Ohne Überwachung und regelmäßigen Abgleich fällt die Lücke oft erst Wochen später auf.
- Geänderte Payload: Der Anbieter ergänzt Felder oder benennt sie um. Ein Empfänger, der starr auf ein festes Format prüft, bricht dann ab.
- Veraltete Konfiguration: Nach einem Umzug der Website zeigt die hinterlegte URL ins Leere, und die Fehlermeldungen des Absenders liest niemand.
Webhook-Test: So prüfen Sie einen Webhook
Für einen Webhook-Test brauchen Sie einen Empfänger, der von außen erreichbar ist, und ein Ereignis, das Sie gezielt auslösen können. Bewährt hat sich diese Reihenfolge:
- Payload ansehen: Zuerst die Meldung an eine temporäre Empfangs-URL schicken, wie sie Dienste wie Webhook.site bereitstellen. So sehen Sie Header und JSON genau so, wie sie ankommen. Nehmen Sie dafür nur Testdaten und keine echten Kundendaten, denn die Daten liegen dann bei einem fremden Dienst.
- Lokal weiterleiten: Für die Entwicklung am eigenen Rechner bieten manche Anbieter Werkzeuge zur Weiterleitung. Mit der Stripe CLI und dem Befehl stripe listen samt Option --forward-to landen Testereignisse auf einem lokalen Port. Das beschreibt Stripe in seiner Webhook-Dokumentation.
- Testereignis auslösen: Die meisten Anbieter haben einen Testmodus oder eine Schaltfläche zum erneuten Senden. Damit prüfen Sie den ganzen Weg bis zur Verarbeitung.
- Fehlerfälle provozieren: Schicken Sie absichtlich eine falsche Signatur (erwartet: Ablehnung) und dieselbe Ereignis-ID zweimal (erwartet: nur eine Verarbeitung). Lassen Sie den Endpunkt außerdem einmal mit einem Serverfehler antworten (erwartet: ein Wiederholungsversuch).
- Protokoll prüfen: Im Dashboard des Absenders nachsehen, welcher Statuscode zurückkam und wie lange die Antwort gedauert hat.
In n8n hat der Webhook-Knoten eine Test-URL und eine Produktions-URL. Die Test-URL nimmt nur Anfragen an, solange der Ablauf im Editor auf ein Ereignis wartet. Ein häufiger Fehler: Die Test-URL wird beim Absender eingetragen, und später wundert man sich, warum nichts mehr ankommt. Details stehen in der n8n-Dokumentation.
Webhooks empfangen: Make, n8n oder eigener Endpunkt
Wer Webhooks nicht programmieren will, kann sie mit einem Automatisierungswerkzeug annehmen. Make erzeugt laut seiner Hilfe eine URL, die eine externe App, ein Dienst oder ein anderes Szenario aufrufen kann. Die Hilfeseite hat eigene Abschnitte zur Fehlerbehandlung und zu einem Ratenlimit für Webhooks. Zur Offenlegung: DigifyNow ist Partner von Make und hat dort einen Empfehlungscode. n8n bietet einen Webhook-Knoten und lässt sich laut Dokumentation auch selbst betreiben. Die dritte Option ist ein eigener Endpunkt im eigenen Code.
| Option | Wo die Webhook-URL entsteht | Wer den Betrieb trägt | Wo es an Grenzen stößt |
|---|---|---|---|
| Make | Im Szenario als Webhook-Modul, betrieben in der Cloud des Anbieters | Make betreibt die Plattform, Sie pflegen das Szenario | Ratenlimit und Abrechnung des Anbieters gelten. Prüfungen wie Idempotenz müssen Sie im Szenario selbst nachbauen. |
| n8n | Im Workflow als Webhook-Knoten mit Test- und Produktions-URL | Je nach Wahl die Cloud des Anbieters oder Sie selbst auf einem eigenen Server | Wer selbst betreibt, kümmert sich auch selbst um Updates, Erreichbarkeit und Backups |
| Eigener Endpunkt | Als Route in einer eigenen Anwendung | Sie oder Ihr Dienstleister | Signaturprüfung, Warteschlange, Wiederholung und Überwachung müssen gebaut und gewartet werden |
Wie richte ich einen Discord-Webhook ein?
In Discord legen Sie einen Webhook in den Servereinstellungen unter „Integrationen“ an. Dort wählen Sie „Webhooks“ und dann „Neuer Webhook“, vergeben einen Namen, wählen den Zielkanal und kopieren die Webhook-URL. Die Bezeichnungen können sich mit App-Updates ändern. Anders als in den meisten Beispielen oben ist Discord hier der Empfänger: Ihr System schickt einen HTTP-POST mit einem JSON-Objekt wie {"content": "Backup fehlgeschlagen"} an diese URL, und die Nachricht erscheint im Kanal. Eine Signatur braucht es dafür nicht. Wer die URL kennt, kann in den Kanal schreiben, deshalb gehört sie nicht in öffentlichen Code. Ist sie doch nach außen gelangt, löschen Sie den Webhook und legen einen neuen an.
Wie DigifyNow mit Webhooks arbeitet
DigifyNow aus Unnau im Westerwald verbindet in Kundenprojekten Systeme wie Formulare, Zahlungsdienste und CRM über Webhooks und APIs. Bei der KI-Automatisierung ist ein Webhook oft der Auslöser eines Ablaufs: Ein Ereignis kommt an, ein KI-Assistent bereitet es auf, und ein Mitarbeiter gibt das Ergebnis frei. Bei einer CRM-Entwicklung planen wir den Empfänger von Anfang an mit ein, samt Signaturprüfung, gespeicherten Ereignis-IDs und Fehlerprotokoll. Ob ein Werkzeug reicht oder ein eigener Endpunkt nötig ist, hängt von drei Fragen ab: Wie viele Ereignisse kommen an? Was passiert, wenn eine Meldung verloren geht? Und wer übernimmt den Betrieb?
Wann sich Unterstützung lohnt
Einen einzelnen Webhook, der Meldungen in einen Chat-Kanal schreibt, richten viele Teams selbst ein. Hilfe von außen lohnt sich, wenn an der Meldung Geld oder Lieferungen hängen, wenn mehrere Systeme in einer festen Reihenfolge reagieren sollen oder wenn intern niemand den Endpunkt überwachen kann. Für ein erstes Gespräch sollten Sie bereithalten: welche Systeme Meldungen senden und empfangen, welche Ereignisse wichtig sind, was bei einer verlorenen Meldung passiert und wer den Betrieb verantwortet. Über die Kontaktseite können Sie eine kostenlose, unverbindliche Einschätzung Ihres Vorhabens anfragen.
Häufige Fragen
Was ist eine Webhook-Payload?
Die Payload ist der Inhalt der HTTP-Anfrage, die ein Webhook verschickt. Meist ist das ein JSON-Objekt mit Ereignistyp, Zeitstempel, einer eindeutigen Ereignis-ID und den betroffenen Daten oder nur deren ID. Die Struktur legt der Absender fest. Sie kann sich mit neuen Versionen ändern, deshalb sollte ein Empfänger unbekannte Felder ignorieren statt abzubrechen.
Brauche ich für Webhooks einen eigenen Server?
Nicht unbedingt. Der Empfänger muss nur über eine öffentliche HTTPS-Adresse erreichbar sein. Das kann ein Automatisierungswerkzeug wie Make oder n8n in der Cloud sein, eine Serverless-Funktion oder eine eigene Anwendung. Bei Make ist DigifyNow Partner. Ein eigener Server lohnt sich, wenn Sie Verarbeitung, Protokolle und Datenhaltung vollständig selbst steuern wollen.
Welchen Statuscode muss ein Webhook-Empfänger zurückgeben?
Ein Erfolgscode aus dem 2xx-Bereich signalisiert dem Absender, dass die Zustellung geklappt hat. Client- oder Serverfehlercodes und ausbleibende Antworten werten viele Anbieter als gescheiterte Zustellung und senden später erneut. Antworten Sie deshalb nach der Signaturprüfung, aber vor der zeitaufwendigen Verarbeitung, und legen Sie die eigentliche Arbeit in eine Warteschlange.
Was bedeutet Idempotenz bei Webhooks?
Idempotent heißt: Wird dieselbe Meldung mehrfach verarbeitet, ist das Ergebnis dasselbe wie bei einer einzigen Verarbeitung. Weil Absender bei Zeitüberschreitungen erneut senden, kommt ein Ereignis manchmal doppelt an. Der Empfänger speichert dafür die Ereignis-ID und überspringt bekannte IDs. Sonst entstehen zum Beispiel zwei Rechnungen für eine Zahlung.