Webhooks

Die fachliche Antwort einer Klinik entsteht erst nach ihrer Prüfung, also lange nach dem POST der Anfrage. Sie kommt deshalb als eigenes Ereignis an eine Adresse, die der Zuweiser vorab als Subscription hinterlegt.

Ereignistypen

eventType	Bedeutung	Payload
AdmissionResponse	FHIR-Antwort auf eine Belegungsanfrage. Überträgt den aktuellen Stand als AdmissionResponseMessage mit Task.	AdmissionResponseEvent

Aufbau einer Zustellung

Das Portal sendet ein POST mit Content-Type: application/json an die hinterlegte Adresse. Der Rumpf ist ein Umschlag mit dem FHIR-Bundle unter body:

{
  "messageId": "f934ef50-aad7-40d5-8513-3cb768ad0dc1",
  "subscriptionId": "0f72c011-fce8-44c1-a393-e0e05e8b9096",
  "eventType": "AdmissionResponse",
  "timestamp": "2025-02-01T10:00:00+00:00",
  "body": {
    "resourceType": "Bundle",
    "type": "message"
  }
}

Ein Empfänger muss also den Umschlag auspacken und body als FHIR-Bundle lesen. Vollständige Beispiele stehen unter Beispiele.

Feld	Bedeutung
messageId	Kennung dieser Zustellung. Eignet sich, um Wiederholungen zu erkennen.
subscriptionId	Die Subscription, über die zugestellt wird.
eventType	Der Ereignistyp, siehe Tabelle oben.
timestamp	Zeitpunkt der Einstellung zur Zustellung.
body	Das FHIR-Bundle.

Inhalt der Nachricht

body ist ein Bundle vom Typ message nach dem Profil AdmissionResponseMessage, mit drei Einträgen: MessageHeader, Task und Organization.

Feld	Bedeutung
id	Kennung des MessageHeader.
eventCoding	Nachrichtentyp, System .../fhir/CodeSystem/message-event, Code admission-request-response.
source.name	Name des sendenden Systems.
source.endpoint	Endpunkt-URL des sendenden Systems.
focus	Verweis auf den Task-Eintrag desselben Bundles.

Der ursprüngliche ServiceRequest bleibt dabei unverändert; die Antwort steckt im Task, der über basedOn auf ihn verweist. Die Task-Felder sind dieselben wie bei der aktiven Abfrage, siehe Tasks. Organization ist die antwortende Klinik, siehe FHIR-Ressourcen.

Zustellung und Wiederholung

Die Antwort des Empfängers steuert, ob das Portal erneut zustellt:

Antwort des Empfängers	Verhalten des Portals
200	Die Zustellung gilt als erfolgreich.
4xx	Dauerhafter Fehler. Es wird nicht erneut zugestellt.
5xx, Zeitüberschreitung, Netzwerkfehler	Vorübergehender Fehler. Das Portal stellt später erneut zu.

Ein Empfänger sollte deshalb nur dann 4xx antworten, wenn er den Inhalt dauerhaft nicht verarbeiten kann. Bei einem vorübergehenden eigenen Problem ist 5xx richtig, damit die Zustellung wiederholt wird.

Da Zustellungen wiederholt werden können, sollte ein Empfänger messageId auswerten und dieselbe Nachricht nicht doppelt verarbeiten.

Die Empfangsadresse für diese Zustellungen wird als Subscription verwaltet.