Zum Hauptinhalt springen

Webhooks und Benachrichtigungen

Webhooks ermöglichen es RxScale, Ihr System in Echtzeit zu benachrichtigen, wenn etwas passiert — zum Beispiel eine Bestellstatusänderung, eine Rezeptunterschrift oder der Versand einer Bestellung durch eine Apotheke. Diese Seite erklärt, wie Sie Webhooks einrichten und effektiv nutzen.

Webhooks einrichten

Um Webhook-Benachrichtigungen zu erhalten:
1

Ihren Endpoint vorbereiten

Erstellen Sie einen HTTP-Endpoint auf Ihrem Server, der POST-Anfragen empfangen kann. Dieser Endpoint sollte öffentlich erreichbar sein und eingehende Webhook-Payloads verarbeiten können.
2

Ihren Webhook registrieren

Verwenden Sie die Management API, um Ihre Webhook-Endpoint-URL zu registrieren. Sie geben an, welche Ereignistypen Sie empfangen möchten.
3

Ihre Einrichtung überprüfen

RxScale sendet ein Testereignis an Ihren Endpoint. Stellen Sie sicher, dass Ihr Server mit einem 200-Statuscode antwortet, um die Funktionsfähigkeit zu bestätigen.
4

Ereignisse empfangen

Nach der Registrierung empfängt Ihr Endpoint Webhook-Benachrichtigungen für die von Ihnen abonnierten Ereignistypen.

Verfügbare Ereignistypen

RxScale sendet Webhook-Benachrichtigungen für eine Vielzahl von Ereignissen. Hier sind die häufigsten: Eine vollständige Liste der Ereignistypen und deren Payload-Formate finden Sie in der Dokumentation Webhook-Ereignisse.

Änderungen der Arztzuordnung einer Verordnung

Wenn Sie Pub/Sub-Benachrichtigungen abonniert haben, kann RxScale ein eigenes Ereignis veröffentlichen, sobald sich der einer Verordnung zugeordnete Arzt ändert. Abonnieren Sie den Benachrichtigungstyp PRESCRIPTION_DOCTOR_CHANGED, um diese Updates zu erhalten. Das Topic muss in Ihrem eigenen Google-Cloud-Projekt liegen; in ein Topic im Projekt von RxScale veröffentlicht RxScale dieses Ereignis nicht. Die Benachrichtigung wird als Verordnungsereignis gesendet. Dabei ist category auf prescription und event auf doctor_changed gesetzt:
Das Objekt data enthält die öffentliche Verordnungsnutzlast sowie die Felder external_provider_identifier, doctor_assignment_reason, old_doctor_uid und new_doctor_uid. old_doctor_uid ist null, wenn der Verordnung vor der Änderung kein Arzt zugeordnet war. new_doctor_uid ist null, wenn die Zuordnung entfernt wurde. doctor_assignment_reason beschreibt, warum RxScale die Zuordnung geändert hat. Stabile Beispiele für Gründe sind ADMIN_ASSIGNED, ORDER_ATTRIBUTE_ASSIGNED, QUEUE_ASSIGNED, PRESCRIPTION_REQUEUED, DOCTOR_REQUEUED_PRESCRIPTIONS, STALE_ASSIGNMENT_CLEARED und ON_HOLD_DOCTOR_REMOVED. Wenn Sie einen Arzt archivieren, kommen dessen offene Verordnungen (wartend oder genehmigt, aber noch nicht signiert) zurück in die Warteschlange. Jede dieser Freigaben sendet doctor_changed mit doctor_assignment_reason DOCTOR_REQUEUED_PRESCRIPTIONS und new_doctor_uid null. Eine interne Zurückstellung (ON_HOLD, noch diesem Arzt zugeordnet) geht an die Organisation zurück: der Status bleibt ON_HOLD, und doctor_changed wird mit doctor_assignment_reason ON_HOLD_DOCTOR_REMOVED und new_doctor_uid null gesendet. Signierte Verordnungen bleiben dem Arzt zugeordnet und lösen dieses Ereignis nicht aus. Das Archivieren storniert die Termine des Arztes nicht und sendet dafür kein patient_doctor_meeting_updated. Die Warteschlangenaufteilung sendet keine eigenen Ereignisse. Das Reservieren einer neuen Verordnung für den Anteilsinhaber ordnet sie niemandem zu, und eine ablaufende Reservierung hebt keine Zuordnung auf — beides erzeugt daher kein doctor_changed-Ereignis. Sie erhalten ein einziges QUEUE_ASSIGNED-Ereignis, sobald ein Arzt die Verordnung annimmt.
Behandeln Sie doctor_assignment_reason als offene Menge. RxScale ergänzt neue Gründe, wenn sich die Prüfabläufe weiterentwickeln. Gehen Sie daher mit unbekannten Werten tolerant um, anstatt die Nachricht abzulehnen.

Bestellstatusänderungen überwachen

Webhooks sind der beste Weg, um über den Fortschritt Ihrer Bestellungen informiert zu bleiben. Anstatt die API wiederholt abzufragen, erhalten Sie eine Benachrichtigung in dem Moment, in dem sich etwas ändert. Ein typischer Überwachungs-Workflow:
  1. Ein Patient gibt eine Bestellung in Ihrem Shop auf.
  2. Sie erhalten einen Webhook, wenn die Bestellung erstellt wird.
  3. Sie erhalten einen Webhook, wenn der Arzt das Rezept genehmigt.
  4. Sie erhalten einen Webhook, wenn das Rezept unterschrieben wird.
  5. Sie erhalten einen Webhook, wenn die Bestellung an eine Apotheke gesendet wird.
  6. Sie erhalten einen Webhook, wenn die Apotheke die Bestellung versendet.
  7. Sie erhalten einen Webhook, wenn die Bestellung abgeschlossen wird.
Jede Benachrichtigung enthält die relevanten Bestell- oder Rezeptdaten, sodass Sie Ihre Systeme aktualisieren und Ihre Patienten in jedem Schritt informieren können.

E-Mail, wenn eine Apotheke eine Bestellung storniert

Soll Ihr Support-Team erfahren, wenn eine Apotheke eine Ihrer Bestellungen storniert, kann RxScale die Support-Adresse Ihres Shops per E-Mail benachrichtigen. Die E-Mail ist standardmäßig aus und wird pro Shop eingeschaltet:
  1. Öffnen Sie in der Admin-App Einstellungen → Shops.
  2. Stellen Sie sicher, dass der Shop eine Support-E-Mail hat. Bearbeiten Sie den Shop, um eine festzulegen.
  3. Öffnen Sie für den Shop Shop konfigurieren und aktivieren Sie Shop-Support per E-Mail benachrichtigen, wenn eine Apotheke eine Bestellung storniert.
Die E-Mail geht jedes Mal raus, wenn die Apotheke eine Pharmacy Order des Shops storniert, im Apothekenportal oder über die Pharmacy API. Storniert RxScale die Bestellung, etwa weil ein Admin sie storniert oder sie an eine andere Apotheke geht, wird keine E-Mail verschickt. Der Betreff nennt die Apotheke, zum Beispiel Apotheke am Markt hat die Pharmacy Order storniert / Apotheke am Markt cancelled the pharmacy order. Der Text ist auf Deutsch und Englisch und enthält:
  • die UID der Pharmacy Order
  • die UID der Order
  • einen Link zur Bestellung in der Admin-App
Im Verlauf der Pharmacy Order wird festgehalten, dass Ihr Support benachrichtigt wurde und an welche Adresse die E-Mail ging. Ein Shop mit aktivierter Einstellung, aber ohne Support-E-Mail, bekommt keine E-Mail. Der Webhook pharmacy_order_updated kommt weiterhin wie bisher. Eine Integration, die Stornierungen schon darüber erkennt, muss nichts ändern.

E-Mail, wenn ein Rezept signiert wird

RxScale kann die Support-Adresse Ihres Shops außerdem jedes Mal per E-Mail benachrichtigen, wenn ein Arzt das Rezept zu einer Bestellung des Shops signiert. Auch diese E-Mail ist standardmäßig aus und wird pro Shop eingeschaltet:
  1. Öffnen Sie in der Admin-App Einstellungen → Shops.
  2. Stellen Sie sicher, dass der Shop eine Support-E-Mail hat. Bearbeiten Sie den Shop, um eine festzulegen.
  3. Öffnen Sie für den Shop Shop konfigurieren und aktivieren Sie Shop-Support per E-Mail benachrichtigen, wenn ein Rezept signiert wird.
Der Betreff nennt die Bestellung mit ihrer Bestellnummer im Shop, zum Beispiel Rezept zur Bestellung #1001 signiert / Prescription for order #1001 signed. Hat die Bestellung keine Bestellnummer im Shop, steht dort die Order-UID von RxScale. Der Text ist auf Deutsch und Englisch und enthält:
  • die UID des Rezepts
  • die UID der Order
  • einen Link zur Bestellung in der Admin-App
Die E-Mail nennt weder Patient noch Medikament. Ein Shop mit aktivierter Einstellung, aber ohne Support-E-Mail, bekommt keine E-Mail.

Best Practices für die Webhook-Verarbeitung

Ihr Endpoint sollte so schnell wie möglich mit einem 200-Statuscode antworten. Verarbeiten Sie den Webhook-Payload bei Bedarf asynchron — blockieren Sie die Antwort nicht, während Sie langwierige Operationen durchführen.
In seltenen Fällen kann dasselbe Webhook-Ereignis mehr als einmal zugestellt werden. Gestalten Sie Ihren Handler idempotent, was bedeutet, dass die zweimalige Verarbeitung desselben Ereignisses keine Probleme verursachen sollte.
RxScale signiert Webhook-Payloads, damit Sie deren Authentizität überprüfen können. Verifizieren Sie die Signatur immer, bevor Sie den Payload verarbeiten. Weitere Details finden Sie unter Webhook-Sicherheit.
Wenn Ihr Endpoint nicht erreichbar ist oder Fehler zurückgibt, werden Webhook-Zustellungen erneut versucht. Richten Sie ein Monitoring ein, um zu erkennen, wenn Ihr Endpoint ausfällt, damit Sie Probleme schnell beheben können.
Führen Sie ein Protokoll aller empfangenen Webhook-Ereignisse. Dies ist von unschätzbarem Wert für die Fehlersuche und das Verständnis der Ereignisabfolge für eine bestimmte Bestellung.

Verwandte Themen