Dokumentation der Nutzung von Callbacks

Warum?

Die Callback-Nutzung soll in der Dokumentation dokumentiert werden, um einerseites für Nutzende ein besseres Verständnis zu schaffen und konkret den SOLL-Zustand der FIT-Connect-Implementierung festzulegen.

Relevante Links und Bemerkungen

Akzeptanzkriterien

  1. Beschreibung: Was ist ein Callback? (Auf Webhooks und vergleichbare Konzepte verweisen)
  2. Es ist anhand eines Code-Beispiels erklärt, wie Callbacks für Sender angelegt und geändert werden können.
  3. Es ist anhand eines Code-Beispiels erklärt, wie Callbacks für Subscriber angelegt und geändert werden können.
  4. Die Vorteile eines Callback im Vergleich zum Polling sind in einem übergreifenden Artikel beschrieben. -> Dies ist bisher nur im Artikel Vorhandensein neuer Einreichungen prüfen beschrieben.
  5. Die Sicherheitsanforderungen inkl. Prüfung von eingehenden Callbacks sind dokumentiert. Siehe submission-api#62 (closed)
  6. Im Artikel Vorhandensein neuer Einreichungen prüfen wird auf den Artikel zur Konfiguration und Prüfung von Callbacks verwiesen.
  7. Es gibt eine Übersicht über alle Callbacks.
    1. Alle Callbacks sind in der API-Spezifikation enthalten.
    2. Die Übersicht über alle Callbacks verlinkt zu jedem Callback auf den jeweiligen Endpunkt der API-Spezifikation, in dem dieser Callback definiert ist.
    3. Zu jedem Callback ist beschrieben, wann dieser Callback ausgelöst wird.
    4. Zu jedem Callback ist beschrieben, an welche Empfänger dieser Callback geschickt wird.
    5. Zu jedem Callback ist ein Beispiel-Callback (Payload) vorhanden.
  8. Für das NewEvents-Callback: Da Onlinedienste mit multiplen Zustelldiensten interagieren können, muss aus der Benachrichtigung ableitbar sein, bei welchem Zustelldienst sich der API-Client das eigentliche Security Event Token abholt. In der API/Dokumentation ist beschrieben, dass eine Zuordnung von Callback zu einem Zustelldienst über die im Callback angegebene submissionId/caseId erfolgen kann. Beim Einreichen einer Submission muss daher im Onlinedienst gespeichert werden, an welchen Onlinedienst diese Submission verschickt wurde. (Hintergrund: Im Callback selbst darf keine Zustelldienst-URL enthalten sein. Drittsystemen wäre es sonst möglich, einen Callback mit manipulierter Zustelldienst-URL an Onlnedienste zu schicken.)

Durchführungsplan (von Entwickler:in bei Umsetzungsplanung auszufüllen)

Edited by Wojciech Gdaniec