APIs & Webhooks
Teil von APIs und Webhooks in Workflows
Einen Webhook mit Beispieldaten testen
Webhook-Zustellung mit Testereignissen prüfen: Signatur, Empfangsantwort und tatsächliche Wirkung im Zielsystem getrennt kontrollieren.
Lösen Sie ein konkretes Ereignis über die tatsächliche Quelle aus und verwenden Sie die dabei erzeugte Nutzlast als Beispieldaten. Prüfen Sie getrennt, ob die Quelle eine Zustellung ausgelöst hat, ob Ihr Endpunkt sie angenommen hat und ob die erwartete Wirkung im Zielsystem eingetreten ist. Eine erfolgreiche HTTP-Antwort belegt nur den Empfang nach der Zustellregel der Quelle.
Einen Testfall vorbereiten
Legen Sie vor dem Auslösen Ereignistyp, erwartete Wirkung und Beobachtungspunkte fest. Für einen GitHub-Repository-Webhook mit dem abonnierten Ereignis issues öffnen Sie ein Issue im konfigurierten Repository. Die von GitHub gesendete Nutzlast ist dabei das konkrete Beispieldatum; prüfen Sie sie in den Zustellungsdetails, statt Werte für eine JSON-Nutzlast zu erfinden.
Zwei weitere GitHub-Testfälle sind ein ping-Ereignis für einen Repository- oder Organisations-Webhook und ein Test-push über die REST API. Der Test-push setzt voraus, dass der Repository-Webhook das Ereignis push abonniert hat. In allen Fällen vergleichen Sie das ausgelöste Ereignis mit der empfangenen Nutzlast und dem vorher festgelegten Ergebnis im Zielsystem.
Für lokale GitHub-Tests können Sie bei smee.io einen neuen Kanal starten, die vollständige Webhook-Proxy-URL kopieren und als Webhook-URL konfigurieren. Leiten Sie damit Zustellungen an einen lokalen Server auf Ihrem Computer oder Codespace weiter. Stripe unterstützt lokales Testen mit der Stripe CLI, bevor eine öffentlich erreichbare HTTPS-URL registriert wird.
Prüfen Sie GitHub-Signaturen vor der weiteren Verarbeitung: GitHub sendet sie im Header X-Hub-Signature-256. Berechnen Sie mit dem Webhook-Secret einen HMAC-Hash über den Payload-Inhalt und vergleichen Sie ihn mit der Signatur; sie beginnt mit sha256=. Behandeln Sie den Payload als UTF-8 und verwenden Sie für den Vergleich eine konstante Zeit vergleichende Funktion statt ==; bewahren Sie das Secret sicher auf.
Bei Stripe beginnt das Signing Secret mit whsec_. Stripe sendet Ereignisse als JSON-Payload; verwenden Sie das Signing Secret für den Handler und testen Sie lokal mit der Stripe CLI.
Zustellung und Zielwirkung beobachten
Beim GitHub-issues-Test ist die ausgelöste Aktion das Öffnen eines Issues im Repository mit dem abonnierten Ereignis. Kontrollieren Sie, ob GitHub eine Lieferung ausweist, welche Nutzlast und Anfrageheader gesendet wurden, welche Antwort der Server zurückgab und ob die zuvor definierte Zielwirkung eingetreten ist.
Beim ping-Test lösen Sie das Ereignis für einen Repository- oder Organisations-Webhook über die REST API aus und prüfen dieselben Beobachtungspunkte. Beim Test-push prüfen Sie zusätzlich, dass der Repository-Webhook push abonniert hat. Eine frühere GitHub-Zustellung lässt sich erneut zustellen.
Für Repository-Webhooks finden Sie die Lieferungen in GitHub unter Repository → Settings → Code and automation → Webhooks → Webhook-URL → Recent deliveries. Öffnen Sie eine Zustellung über ihre GUID. Die Ansicht umfasst für die vergangenen drei Tage Anfrageheader, Nutzlast, Versandzeitpunkt und empfangene Serverantwort; zum Anzeigen ist Admin-Zugriff auf das Repository erforderlich.
Notieren Sie je Versuch Ereignisart, Zustellkennung, Zeitpunkt, Endpunktantwort und tatsächliches Ergebnis im Zielsystem. Die Ansicht der Zustellung ersetzt diese letzte Kontrolle nicht.
| Versuch mit Beispieldaten | Erwartung am Empfänger | Erwartung im Zielsystem |
|---|---|---|
| Relevantes gültiges Ereignis | Nachricht und Ereignistyp werden nach den Regeln der Quelle geprüft und angenommen. | Die vorgesehene Testaktion ist erkennbar. |
| Nicht relevanter Ereignistyp oder andere Aktion | Keine fachliche Verarbeitung dieses Falls. | Keine Wirkung für diesen Vorgang. |
| Ungültige Signatur bei signierter Quelle | Nachricht wird zurückgewiesen. | Keine Wirkung. |
| Fehlende benötigte Angabe | Der Fall bleibt als nicht zuordenbar erkennbar. | Kein stilles Schreiben mit Ersatzwert. |
| Erneute Zustellung | Der weitere Empfang ist nachvollziehbar. | Die tatsächliche Wirkung wird erneut kontrolliert. |
Welche HTTP-Antwort bei einem fachlich unbrauchbaren, aber technisch gültigen Ereignis richtig ist, hängt vom Zustellvertrag der Quelle und vom eigenen Wiederanlauf ab.
Einen Fehlschlag eingrenzen
Erscheint bei der Quelle keine Zustellung, prüfen Sie Abonnement, Ereignisauswahl und Auslöser. Wird eine Zustellung als fehlgeschlagen angezeigt, prüfen Sie Erreichbarkeit, TLS, Pfad und die empfangene Serverantwort. Kommt die Meldung an, aber die erwartete Zielwirkung fehlt, prüfen Sie die eigene Verarbeitung und nachgelagerte API-Aufrufe.
GitHub erwartet eine 2xx-Antwort innerhalb von zehn Sekunden. Microsoft Graph betrachtet eine Änderungsbenachrichtigung bei einer 2xx-Antwort innerhalb von drei Sekunden als zugestellt; für längere Verarbeitung empfiehlt Microsoft, die Benachrichtigung zu prüfen und verlässlich zu speichern, bevor der Endpunkt 202 Accepted zurückgibt. Diese Fristen gelten jeweils nur für den genannten Dienst.
Halten Sie Eingabe, erwartete Wirkung, beobachtete Zustellung, tatsächliches Zielergebnis und Abweichung fest. Eine erneute Zustellung prüft, ob der Empfang nachvollziehbar bleibt; die Absicherung gegen doppelte fachliche Aktionen erfordert eine eigene Prüfung.
