APIs & Webhooks
Teil von APIs und Webhooks in Workflows
Webhooks und regelmäßige Abfragen vergleichen
Webhooks und geplante API-Abfragen anhand von Verzögerung, Schnittstelle, Empfang und Wiederanlauf für einen Workflow vergleichen.
Wählen Sie einen Webhook, wenn ein Dienst die benötigte Änderung meldet und Ihr Workflow diese Meldung zuverlässig empfangen kann. Eine regelmäßige Abfrage passt, wenn Sie den Abruf selbst steuern müssen oder kein geeignetes Ereignis verfügbar ist.
Ausschlaggebend sind die zulässige Verzögerung, die angebotenen Schnittstellen und ein verlässlicher Weg, verpasste Änderungen zu erkennen.
Die benötigte Reaktionszeit festlegen
Bei einer regelmäßigen Abfrage wird eine Änderung frühestens bei einem erfolgreichen Abruf erkennbar, der sie bereits enthält. Ein kürzerer Abstand erzeugt mehr Anfragen, garantiert aber keine sofortige Verarbeitung: Läufe können ausfallen, und eine Quelle kann Änderungen verzögert bereitstellen.
Ein Webhook kann früher auf ein Ereignis aufmerksam machen; auch seine Zustellung und Verarbeitung können sich verzögern.
Formulieren Sie eine Anforderung wie: „Eine neue Anfrage soll innerhalb des vereinbarten Zeitfensters sichtbar sein.“ Prüfen Sie dann, ob die verfügbare Ereigniszustellung oder ein zulässiger Abfrageplan dazu passt.
Schnittstelle und Wiederanlauf vergleichen
| Prüfpunkt | Webhook | Regelmäßige Abfrage |
|---|---|---|
| Angebot der Quelle | Benötigter Ereignistyp und ausreichende Angaben müssen verfügbar sein. | Eine geeignete Lese- oder Änderungsabfrage muss verfügbar sein. |
| Eigener Betrieb | Zustellungen annehmen, Meldungen prüfen und rechtzeitig bestätigen. | Abrufe planen und alle gelieferten Ergebnisse verarbeiten. |
| Datenstand | Eine Meldung kann einen weiteren API-Aufruf für aktuelle Daten erfordern. | Der Abruf liefert den von der jeweiligen API definierten Stand oder Änderungsbestand. |
| Unterbrechung | Zustellversuche und Nachholweg des Anbieters prüfen. | Prüfen, wie die API seit dem letzten vollständig verarbeiteten Stand weitergelesen werden kann. |
Microsoft Graph bietet für unterstützte Ressourcen Änderungsbenachrichtigungen als Push-Verfahren und Delta-Abfragen als Pull-Verfahren. Bei einer Delta-Abfrage führt @odata.nextLink zu weiteren Seiten; erst @odata.deltaLink kennzeichnet das Ende dieses Durchlaufs und dient als Ausgangspunkt für spätere Änderungen. Ob die konkrete Ressource beide Verfahren unterstützt, ist zu prüfen.
Betriebsgrenzen der Quelle beachten
Ein Webhook erspart nicht zwangsläufig einen API-Aufruf. Seine Meldung kann nur das betroffene Objekt benennen; der aktuelle Inhalt muss dann gesondert gelesen werden.
Für Microsoft Graph benötigt die Webhook-Zustellung einen öffentlich erreichbaren HTTPS-Endpunkt und ein gültiges Abonnement. Andere Dienste legen ihre eigenen Empfangsregeln fest.
Auch eine Abfrage ohne neue Treffer verbraucht Anfragen. Prüfen Sie, ob die Quelle Änderungsmarker, bedingte Anfragen oder einen Delta-Endpunkt anbietet. Bei Listen müssen alle relevanten Seiten gelesen werden. GitHubs REST-API verwendet bei paginierten Ergebnissen beispielsweise einen link-Header für weitere Seiten.
Wichtige technische Hinweise zu Webhooks und Abfragen
- Microsoft Graph: Delta-Abfrage
- Verwendet `@odata.nextLink` für Seiten und `@odata.deltaLink` zum Fortsetzen nach Unterbrechung.
- GitHub: Paginierung
- Verwendet `link`-Header für weitere Seiten bei paginierten Ergebnissen.
- Webhook-Anforderung
- Benötigt öffentlich erreichbaren HTTPS-Endpunkt und gültiges Abonnement.
Die Wahl am eigenen Fall prüfen
Für eine interne Aufgabenliste, die neue Fälle aus einem Fremdsystem übernimmt, genügen zunächst drei Fragen: Wie schnell muss ein Fall sichtbar sein? Gibt es ein passendes Ereignis oder einen verlässlichen Änderungsabruf? Wie findet der Workflow Änderungen wieder, die während einer Unterbrechung entstanden sind?
Gehen Sie eine einzelne Änderung, mehrere Änderungen zwischen zwei Kontakten und einen längeren Ausfall gedanklich durch. Kann die Quelle verpasste Ereignisse nicht zuverlässig nachliefern, braucht der Entwurf einen gesonderten Abgleich. Ein geeigneter Änderungsabruf kann allein genügen oder Ereignismeldungen ergänzen.
