Um einen Webhook zu testen, geben Sie dem Anbieter eine erreichbare URL, lösen ein reales Ereignis aus und bestätigen dann, dass Ihr Handler die Nutzlast akzeptiert und korrekt reagiert. Der schwierige Teil ist, dass Ihre Anwendung der Empfänger und nicht der Aufrufer ist, sodass Sie nicht einfach auf „Senden“ klicken und die Antwort lesen können. Dieser Leitfaden führt Sie durch die benötigten Tools (Inspektionsdienste, lokale Tunnel, Anbieter-Trigger) und einen wiederholbaren Prozess, um Ihren Handler Ende-zu-Ende zu überprüfen.
Warum Webhooks schwieriger zu testen sind als normale APIs
Bei einem normalen API-Aufruf steuern Sie die Anfrage. Sie wählen die Methode, legen den Body fest, senden ihn ab und lesen die Antwort. Webhooks kehren das um. Der Anbieter sendet die Anfrage nach eigenem Zeitplan mit einer von ihm definierten Nutzlast an Sie. Dieser Rollentausch führt zu vier Testproblemen.
Erstens können Sie das Ereignis standardmäßig nicht selbst auslösen. Ein payment_intent.succeeded-Ereignis wird nur ausgelöst, wenn Stripe dies entscheidet, daher benötigen Sie Anbieter-Tools, um eines zu erzwingen.
Zweitens ist die Zustellung asynchron. Das Ereignis trifft ein, sobald die vorgelagerte Aktion abgeschlossen ist, sodass Ihr Test eine eingehende Anfrage erfassen muss, anstatt auf einen Rückgabewert zu warten.
Drittens wird die Form der Nutzlast vom Anbieter definiert. Ihr Handler muss genau das parsen, was GitHub, Stripe oder Slack sendet.
Viertens signieren die meisten Anbieter ihre Anfragen. Ihr Endpunkt muss einen Signatur-Header überprüfen, bevor er dem Body vertraut, und ein Test, der dies überspringt, verbirgt echte Fehler. Für einen tieferen Einblick lesen Sie unseren Leitfaden zur Webhook-Signaturprüfung.
Wenn Sie noch unentschlossen sind, ob Webhooks überhaupt das richtige Muster für Ihre Integration sind, vergleichen Webhooks vs. Polling und Webhook vs. WebSocket die Kompromisse.
Das Webhook-Test-Toolkit
Sie werden vier Arten von Tools verwenden, oft in derselben Sitzung: einen Erfassungsdienst, um Roh-Nutzlasten zu sehen, einen Tunnel, um Ihren Laptop zu erreichen, Anbieter-Trigger, um reale Ereignisse auszulösen, und ein Assertions-Tool, um Ihren Handler zu überprüfen.
1. Inspektions- und Erfassungsdienste
Bevor Sie eine einzige Zeile Handler-Code schreiben, richten Sie den Anbieter auf eine Wegwerf-URL und schauen Sie, was er tatsächlich sendet. Diese Dienste stellen Ihnen einen öffentlichen Endpunkt zur Verfügung und zeigen jede Anfrage in Echtzeit an.
webhook.site bietet Ihnen eine einzigartige zufällige URL und E-Mail-Adresse, sobald die Seite geladen wird. Alles, was dorthin gesendet wird, erscheint sofort: vollständiger Body, Header und Methode. Kostenlose URLs verfallen nach 7 Tagen und sind auf 100 Anfragen begrenzt, mit einer maximalen Anfragengröße von 10 MB. Kostenpflichtige Pläne umfassen permanente URLs, unbegrenzte Anfragen und eine gespeicherte Historie der letzten 10.000 Anfragen.
Beeceptor bietet einen kostenlosen HTTPS-Endpunkt, den Sie als Webhook-Empfänger verwenden und eingehende Nutzlasten in Echtzeit inspizieren können. Es bietet auch Mock-Server-Endpunkte, sodass Sie mit demselben Tool erfassen und simulieren können.
Pipedream RequestBin ist ein weiteres weit verbreitetes Tool zur Anforderungserfassung. Überprüfen Sie die aktuellen Dokumente auf Stufenspezifikationen, da Erfassungsdienste ihre kostenlosen Limits häufig ändern.
Verwenden Sie diese, um eine Frage zu beantworten: Wie sieht die reale Nutzlast aus? Kopieren Sie ein Beispiel für später, wenn Sie wiederholbare Tests erstellen.
2. Lokale Entwicklung: localhost mit einem Tunnel zugänglich machen
Anbieter können localhost:3000 auf Ihrem Rechner nicht erreichen. Ein Tunnel erstellt eine öffentliche HTTPS-URL, die den Traffic an Ihren lokalen Port weiterleitet, sodass Sie Ihren Handler in Ihrem Editor ausführen und live debuggen können.
ngrok ist die gängige Wahl. Installieren Sie es, authentifizieren Sie sich einmal, und leiten Sie dann einen Port weiter.
brew install ngrok # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000 # forwards a public HTTPS URL to localhost:3000
Kostenlose ngrok-Konten erhalten eine automatisch gewählte Entwicklungsdomain. Benutzerdefinierte Domains erfordern einen kostenpflichtigen Plan.
cloudflared führt einen schnellen Tunnel mit einem einzigen Befehl aus, wenn Sie Cloudflare bevorzugen.
cloudflared tunnel --url http://localhost:3000
Fügen Sie die öffentliche URL, die der Tunnel ausgibt, in die Webhook-Einstellungen des Anbieters ein, und eingehende Ereignisse landen auf Ihrem lokalen Server. Für eine detailliertere Anleitung zu diesem Muster lesen Sie wie man localhost-APIs mit Webhook-Diensten testet.
3. Test-Ereignisse vom Anbieter auslösen
Eine Erfassungs-URL hilft nur, wenn etwas daran gesendet wird. Die meisten großen Anbieter liefern Tools, um Test-Ereignisse bei Bedarf auszulösen, sodass Sie keine echten Zahlungen oder Push-Nachrichten erzeugen müssen.
Die **Stripe CLI** ist das sauberste Beispiel. Der Befehl stripe listen leitet Live-Ereignisse von Ihrer Stripe-Sandbox an einen lokalen Pfad weiter und gibt ein Webhook-Signaturgeheimnis aus, das Sie in Ihre App-Konfiguration einfügen.
# Forward all events to your local handler:
stripe listen --forward-to localhost:3000/webhooks
# Filter to specific events only:
stripe listen --events payment_intent.succeeded,checkout.session.completed \
--forward-to localhost:3000/webhooks
Wenn der Listener läuft, löst stripe trigger ein Test-Ereignis aus. Beachten Sie, dass das Auslösen ordnungsgemäß unterstützte API-Objekte erstellt und Nebenwirkungen hat: payment_intent.succeeded gibt auch payment_intent.created aus.
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help # list every supported event
**GitHub** speichert eine kurze Zustellhistorie, die Sie wiedergeben können. Gehen Sie zu Ihrem Repository, dann zu Einstellungen, dann zu Webhooks unter „Code und Automatisierung“. Klicken Sie auf die Webhook-URL, öffnen Sie den Tab „Kürzliche Zustellungen“, klicken Sie auf eine Zustell-GUID und klicken Sie auf „Erneut zustellen“. Zwei Einschränkungen sind wichtig: Sie können Zustellungen nur aus den letzten 3 Tagen erneut zustellen, und Sie benötigen Administratorzugriff auf das Repository. GitHub stellt fehlgeschlagene Zustellungen nicht automatisch erneut zu, daher ist die Wiederholung manuell.
Eingehende **Slack**-Webhooks sind am einfachsten zu testen. Sie senden eine Nachricht, indem Sie JSON an die Webhook-URL POSTen. Die minimale Nutzlast ist nur ein text-Feld.
curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
-H 'Content-type: application/json' \
-d '{"text":"Hello, world."}'
Die Slack-Webhook-URL ist ein Geheimnis. Slack widerruft URLs, die durchsickern, also halten Sie sie aus clientseitigem Code und öffentlichen Repos fern.
4. Ihren Handler überprüfen
Das Erfassen und Auslösen beweist, dass die Verkabelung funktioniert. Sie beweisen nicht, dass Ihr Handler korrekt ist. Das letzte Tool sendet eine speziell angefertigte Nutzlast und überprüft die Antwort sowie die Nebenwirkungen. Im Grunde ist das ein curl-Befehl mit einem repräsentativen Body.
curl -X POST http://localhost:3000/webhooks \
-H 'Content-Type: application/json' \
-H 'Stripe-Signature: t=...,v1=...' \
-d '{"id":"evt_test","type":"payment_intent.succeeded","data":{"object":{"id":"pi_123","status":"succeeded"}}}'
Ein einziger curl-Befehl ist für einen Smoke-Test ausreichend. Er reicht nicht aus, wenn Sie wiederholbare, überprüfte Tests wünschen, die in CI ausgeführt werden. Hier kommt ein spezielles API-Tool ins Spiel.
Webhooks mit Apidog testen
Apidog ist eine All-in-One-API-Plattform zum Entwerfen, Debuggen, Testen, Mocken und Dokumentieren von APIs. Es verfügt über keine dedizierte „Webhook-Inbox“, daher ist dieser Abschnitt ehrlich darüber, was es tatsächlich gut kann: Nutzlasten erstellen, speichern, Antworten überprüfen und einen Anbieter mit einem Mock-Server ersetzen.
Eine Beispiel-Nutzlast als wiederverwendbare Anfrage erstellen und speichern
Nehmen Sie die Nutzlast, die Sie von webhook.site erfasst (oder aus den Dokumenten eines Anbieters kopiert) haben, und bauen Sie sie in eine Apidog-Anfrage ein. Stellen Sie die Methode auf POST ein, fügen Sie den JSON-Body ein und fügen Sie die Header hinzu, die der Anbieter sendet, einschließlich des Signatur-Headers, den Ihr Handler überprüft.
Speichern Sie diese Anfrage für Ihren Endpunkt. Jetzt haben Sie eine wiederholbare, versionskontrollierte Möglichkeit, eine bekanntermaßen gute (oder absichtlich fehlerhafte) Nutzlast an Ihren Handler zu POSTen, anstatt jedes Mal einen curl-Befehl neu einzugeben.
Die Antwort mit dem visuellen Assertions-Builder überprüfen
Das Senden der Nutzlast ist die Hälfte des Tests. Die andere Hälfte ist die Überprüfung, was Ihr Handler zurückgibt. Im Anforderungs- oder Szenario-Schritt öffnen Sie die Post Processors, klicken auf „+ Hinzufügen“ und wählen „Assertion“. Apidog fügt eine Validierungsregel hinzu, die Sie ohne Code konfigurieren.
Richten Sie die Assertion auf den Antwort-Body und verwenden Sie $ für die JSON-Wurzel. Zielen Sie zum Beispiel auf $.data.status, setzen Sie die Bedingung auf Gleich und vergleichen Sie mit succeeded. Führen Sie die Anfrage aus, und das Ergebnis wird im Assertion-Tab angezeigt. Visuelle Assertions vergleichen Werte als Zeichenketten. Wenn Sie typgenaue Prüfungen (eine reelle Zahl, einen booleschen Wert) benötigen, wechseln Sie zu einem benutzerdefinierten Skript unter Verwendung der Postman-kompatiblen pm.test-Syntax.
Dies verwandelt „es gab einen 200er-Status zurück“ in „es gab einen 200er-Status zurück, das Statusfeld ist succeeded und die Bestell-ID stimmt überein“. Bauen Sie mehrere Assertions in ein Szenario ein, um den Erfolgsfall, einen fehlenden Feld-Fall und eine Ablehnung aufgrund einer ungültigen Signatur abzudecken.
Einen Mock-Server als Ersatz für den Anbieter verwenden
Manchmal möchten Sie die andere Richtung testen: einen Dienst in Ihrem Stack, der einen Anbieter aufruft. Beim lokalen Testen möchten Sie den echten Anbieter möglicherweise gar nicht ansprechen. Apidogs Mock-Server ermöglicht es Ihnen, diesen zu ersetzen.
Apidog bietet drei Mock-Typen an. Local Mock läuft mit dem Desktop-Client und funktioniert nur, während der Client geöffnet ist. Cloud Mock wird auf Apidog-Servern gehostet, läuft 24/7 und kann ein- oder ausgeschaltet werden (standardmäßig ist es ausgeschaltet). Runner Mock läuft auf selbst gehosteter Runner-Infrastruktur und wird teamübergreifend geteilt. Jeder HTTP-Endpunkt verfügt über ein Mock-Modul; kopieren Sie die Mock-URL vom API-Tab im Design-Modus oder vom Mock-Tab im Debug-Modus. Nur Pfade, die mit / beginnen, werden an die Mock-Umgebung weitergeleitet. Richten Sie Ihren Code während der Tests auf diese Mock-URL, und Ihre Integration erhält vorhersagbare Anbieterantworten ohne echte API-Aufrufe oder Nebenwirkungen.
Webhook-Tests in CI mit der Apidog CLI ausführen
Sobald Ihr Szenario lokal erfolgreich ist, führen Sie es bei jedem Push mit der Apidog CLI aus. Es erfordert Node.js v16 oder neuer.
npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog # verify install
Führen Sie ein gespeichertes Szenario online aus, indem Sie das Zugriffstoken und die IDs aus dem CI/CD-Tab „Befehlszeile“ des Szenarios übergeben.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
Hier ist -t das Testszenario, -e die Umgebung (erforderlich), -d die Testdaten (ein CSV- oder JSON-Dateipfad oder eine gespeicherte Datensatz-ID) und -r legt die Reporter fest, die cli, html, json und junit akzeptieren. Für eine vollständige Befehlszeilen-Anleitung siehe das Apidog CLI Tutorial.
Möchten Sie Ihre eigenen Webhook-Tests visuell erstellen und überprüfen? Probieren Sie Apidog kostenlos aus, keine Kreditkarte erforderlich.
Ein Schritt-für-Schritt-Workflow für das Testen von Webhooks
Wenn man die Tools zusammenführt, ergibt sich folgende wiederholbare Reihenfolge.
- Die reale Nutzlast inspizieren. Richten Sie den Anbieter auf eine webhook.site-URL und erfassen Sie ein reales Ereignis. Notieren Sie sich die Body-Form, die Header und das Signaturformat.
- Ihren Code erreichen. Starten Sie Ihren Handler lokal, öffnen Sie einen Tunnel mit
ngrok http 3000odercloudflared, und fügen Sie die öffentliche URL in die Webhook-Konfiguration des Anbieters ein. - Ein reales Ereignis auslösen. Verwenden Sie
stripe trigger, den Redeliver-Button von GitHub oder einen Slack-POST, um ein echtes Ereignis durch den Tunnel zu senden. - Signaturbehandlung überprüfen. Senden Sie dieselbe Nutzlast mit einer gültigen Signatur und erneut mit einer manipulierten. Ihr Handler muss die erste akzeptieren und die zweite ablehnen.
- Die Antwort und Nebenwirkungen überprüfen. Speichern Sie die Nutzlast als Apidog-Anfrage, fügen Sie Assertions für den Antwort-Body und den Status hinzu und bestätigen Sie, dass der Datenbankeintrag oder der nachgelagerte Aufruf stattgefunden hat.
- Automatisieren Sie es. Verschieben Sie das Szenario in die Apidog CLI, damit es bei jeder Änderung in CI ausgeführt wird.
Wenn Sie das Webhook-System selbst entwerfen, anstatt es nur zu nutzen, behandeln wie man zuverlässige Webhooks entwirft und Best Practices für Zahlungs-Webhooks Wiederholungsversuche, Idempotenz und Sicherheit. Für das Gesamtbild erklären der Webhook-API-Leitfaden und Webhooks und ereignisgesteuerte Architektur, wo Webhooks in ein größeres System passen.
Häufig gestellte Fragen
Wie testet man einen Webhook?
Geben Sie dem Anbieter eine erreichbare URL, lösen Sie ein echtes oder Test-Ereignis aus und bestätigen Sie dann, dass Ihr Handler die Nutzlast empfängt, die Signatur überprüft, den richtigen Status zurückgibt und den erwarteten Nebeneffekt ausführt. Erfassen Sie zuerst eine reale Nutzlast und erstellen Sie dann eine wiederholbare Anfrage mit Assertions, damit der Test jedes Mal auf die gleiche Weise abläuft.
Wie testet man Webhooks lokal?
Führen Sie Ihren Handler auf einem lokalen Port aus und machen Sie ihn dann mit einem Tunnel zugänglich, damit der Anbieter Ihren Rechner erreichen kann. Verwenden Sie ngrok http 3000 oder cloudflared tunnel --url http://localhost:3000, fügen Sie die öffentliche HTTPS-URL in die Webhook-Einstellungen des Anbieters ein und lösen Sie ein Ereignis aus. Eingehende Anfragen landen auf Ihrem lokalen Server, wo Sie Breakpoints setzen und sie live inspizieren können.
Wie testet man einen Webhook mit Postman?
Postman kann eine speziell angefertigte Nutzlast an Ihren Endpunkt POSTen und die Antwort überprüfen, aber es kann keinen echten eingehenden Webhook eigenständig empfangen. Dasselbe gilt für Apidog: Sie erstellen eine Anfrage mit der Nutzlast und den Headern des Anbieters, fügen Assertions für den Antwort-Body und den Status hinzu und speichern sie als wiederverwendbaren Test. Um ein echtes eingehendes Ereignis zu erfassen, kombinieren Sie das Tool mit einem Erfassungsdienst oder einem Tunnel.
Wie testet man Stripe-Webhooks?
Verwenden Sie die Stripe CLI. Führen Sie stripe listen --forward-to localhost:3000/webhooks aus, um Sandbox-Ereignisse an Ihren Handler weiterzuleiten und ein Signaturgeheimnis zu erhalten. Führen Sie dann stripe trigger payment_intent.succeeded (oder ein beliebiges Ereignis von stripe trigger --help) aus, um ein echtes Test-Ereignis auszulösen. Das Auslösen erstellt unterstützte API-Objekte und kann kaskadieren, sodass payment_intent.succeeded auch payment_intent.created ausgibt.
Wie testet man einen Slack-Webhook?
POSTen Sie JSON an die eingehende Webhook-URL. Die minimale gültige Nutzlast ist {"text":"Hello, world."}, gesendet mit einem Content-type: application/json-Header. Ein erfolgreicher Test postet die Nachricht in den konfigurierten Kanal. Halten Sie die URL geheim, da Slack Webhook-URLs widerruft, die durchsickern.
Wie testet man eine Webhook-URL?
Senden Sie einen Beispiel-POST an die URL und bestätigen Sie, dass sie einen Erfolgsstatus zurückgibt und sich korrekt verhält. Die schnellste Überprüfung ist ein einzelner curl-Befehl mit einem repräsentativen Body. Für einen echten Test erfassen Sie zuerst eine tatsächliche Nutzlast, senden Sie diese sowohl mit gültigen als auch ungültigen Signaturen und überprüfen Sie die Antwort und die Nebenwirkungen, anstatt nur auf einen 200er-Status zu prüfen.