InnerWeb
Zum Inhalt springen

Checkliste zur Abnahme der Webhook- und API-Integration im Werk

Die Abnahme einer Integration auf Basis von Webhooks und API sollte sich auf eine einzige Kontrollliste stützen, die Integrator und IT-Leiter gemeinsam in der Pilotphase abhaken. Wir haben zwölf Punkte zusammengestellt: Zustellmodus, Grenzen der Outbox, Bestätigungen der Zustellung, maschinelles Token und Antwortcodes. Jeder Punkt hat eine Erläuterung, woran man erkennt, dass er erfüllt ist.

89
Einträge in einem Paket des Pollers
Quelle: Funktionskarte
300 s
Dauer der Reservierung eines Eintrags vor der Rückgabe in den Pool
Quelle: Funktionskarte

Warum die Abnahme eine Liste braucht

Eine Webhook-Integration arbeitet an der Schnittstelle zweier Systeme und zweier Teams. Dabei kommt es leicht vor, dass jede Seite annimmt, die andere habe einen kritischen Punkt geprüft. Die Kontrollliste sorgt dafür, dass jeder Punkt einen Verantwortlichen und einen Nachweis hat.

In der Pilotphase sind die Kosten eines Fehlers am niedrigsten: Das Datenaufkommen ist gering und das Team beobachtet die Ergebnisse genau. Eine Abnahme nach dem Piloten erlaubt es, mit dem Wissen in die Einführung zu gehen, welche Grenzen akzeptabel sind und welche eine Lösung brauchen.

Zustellmodus und seine Grenzen

Die erste Entscheidung betrifft den Zustellmodus. Die Einstellung webhook:delivery_mode kennt zwei Werte: direct, den Standard, und outbox. Jeder andere Wert als outbox bedeutet direct, ein Tippfehler in der Einstellung schaltet also stillschweigend den direkten Modus ein. Prüfen Sie den Wert im Panel und halten Sie ihn im Protokoll fest.

Der Modus outbox schreibt den Inhalt des Webhooks in eine Tabelle, und ein externer Poller holt die Einträge ab und sendet sie mit derselben Nutzlast weiter. Er wurde für Anlagen entwickelt, in denen das Netz den ausgehenden Verkehr vom Host der Anwendung blockiert. Er hat jedoch Grenzen, die die Abnahme berücksichtigen muss.

Grenzen, die man akzeptieren oder umgehen muss

Die Outbox kennt keine Obergrenze für Versuche, keinen Abstand zwischen Wiederholungen und keinen Alarm für hängengebliebene Einträge. Auch eine Aufgabe zum Aufräumen der Tabelle fehlt, daher wachsen abgeschlossene Einträge unbegrenzt. Eine nicht bestätigte Zustellung mit failed setzt den Eintrag zurück in den Status pending und erhöht den Zähler der Versuche, sodass der Poller ihn ohne Ende wiederholt.

Die Abnahme sollte dokumentieren, wer auf Seiten des Werks die hängengebliebenen Einträge überwacht und wie die Tabelle wächst. Das ist kein Mangel, den man verbirgt, sondern eine bekannte Grenze, die die Organisation mit einem Verfahren abdeckt.

Kennwerte der Abnahme der Outbox

Kennwerte der Abnahme der OutboxBalkendiagramm: Paket des Pollers 89 Einträge, Reservierung 300 Sekunden, 6 Typen von Ereignissen der Rezeption.0100200300AnzahlEinträge im Paket: 89 Anzahl89 AnzahlEinträge im PaketSekunden der Reservierung: 300 Anzahl300 AnzahlSekunden der ReservierungTypen von Ereignissen der Rezeption: 6 Anzahl6 AnzahlTypen von Ereignissen derRezeption
Quelle: Funktionskarten der Outbox für Webhooks und der Ereignisse der Rezeption

Bestätigungen und Wiederholungen

Das Abholen der ausstehenden Einträge reserviert atomar ein Paket von bis zu 89 Einträgen unter einer Schreibsperre in einer Transaktion, sodass zwei Poller nicht denselben Eintrag erhalten. Ein Eintrag im Status delivering, dessen Reservierung länger als 300 Sekunden dauert, kehrt in den Pool zurück und kann erneut abgeholt werden.

Die Bestätigung der Zustellung nimmt den Status delivered oder failed mit einer optionalen Fehlerbeschreibung an und ist idempotent: Die Bestätigung eines bereits zugestellten Eintrags ändert nichts. Die Abnahme sollte einen Test umfassen, bei dem der Poller dieselbe Bestätigung zweimal sendet und sich nichts ändert.

API und maschinelles Token

Aufrufe der API erfordern ein maschinelles Token. Die Abnahme prüft, dass das Token auf Seiten des Servers aufbewahrt wird und nicht im Code des Browsers, und dass ein falsches oder fehlendes Token die Antwort 401 liefert. Bei Zugangsanträgen bedeutet die Antwort 201 einen neuen Antrag, 200 die Wiederholung derselben Anfrage-ID und 400 fehlerhafte Daten.

Prüfen Sie außerdem, dass ein wiederholter Aufruf mit derselben Anfrage-ID kein Duplikat erzeugt. Das ist der häufigste Fehler bei Integrationen, die im Test mit einem einzigen Aufruf funktionieren und im Betrieb Aufrufe wiederholen, wenn keine Antwort kommt.

Wie die Abnahme durchgeführt wird

Die Abnahme führen Sie in einer gemeinsamen Sitzung mit dem Integrator und dem IT-Leiter durch. Jeder Punkt der Liste endet mit einem Nachweis: einem Screenshot der Einstellung, einem Eintrag im Kanal oder einer Antwort mit einem Code. Ohne Nachweis gilt der Punkt als nicht erfüllt.

Nicht erfüllte Punkte kommen auf eine kurze Liste der Korrekturen mit Termin, und die Abnahme gilt erst als abgeschlossen, wenn sie geschlossen sind. Die Liste samt Nachweisen gehört zur Dokumentation der Integration und dient bei einer Prüfung als Beleg.

Checkliste

Videomaterial

Häufig gestellte Fragen

Wann sollte die Abnahme der Integration stattfinden?

Am Ende der Pilotphase, wenn echter Verkehr anliegt und das Team noch Zeit für Korrekturen hat, ohne unter Produktionsdruck zu stehen.

Garantiert die Outbox, dass kein Eintrag verloren geht?

Der Eintrag bleibt bis zur Bestätigung in der Tabelle, aber es gibt keine Obergrenze für Versuche und keinen Alarm für hängengebliebene Einträge. Deshalb braucht die Abnahme ein Verfahren zur Überwachung.

Darf eine Bestätigung mehrfach gesendet werden?

Ja. Die Bestätigung eines bereits zugestellten Eintrags ist idempotent und ändert nichts.

Führen Sie die Abnahme mit unserem Team durch

Wir stellen für den Integrator und die IT ein Abnahmeprotokoll auf Basis dieser Liste bereit. Vereinbaren Sie ein Gespräch mit InnerWeb.

Sprechen wir