Webhook-Ereignisse
RxScale sendet Webhooks für die folgenden Ereignistypen:HTTP-Header
Webhook-Anfragen enthalten die folgenden HTTP-Header:
Falls Sie beim Erstellen des Abonnements einen benutzerdefinierten Header konfiguriert haben, wird dieser ebenfalls mitgesendet. Test-Webhooks sind nicht signiert und enthalten stattdessen den Header
X-Webhook-Test: true.
pharmacy_order_created
Wird gesendet, wenn eine neue Apothekenbestellung erstellt und Ihrer Apotheke zugewiesen wird.Eine Apothekenbestellung wird pro Fulfillment erstellt, nicht pro Shop-Bestellung. Eine Shop-Bestellung kann daher im Lauf der Zeit mehrere Apothekenbestellungen erzeugen — zum Beispiel, wenn sie in mehrere Fulfillments aufgeteilt wird oder später ein Fulfillment hinzukommt. Diese Apothekenbestellungen haben dieselbe
data.order.uid. Verwenden Sie data.uid als Schlüssel einer Apothekenbestellung; shop_order_name ist nicht eindeutig. Details finden Sie unter Apothekenbestellungen.Apothekenbestellungen werden auch für rezeptfreie (OTC) Käufe erstellt, nicht nur für rezeptpflichtige Bestellungen — jede Ihrer Apotheke zugewiesene Erfüllung löst dieses Ereignis aus, unabhängig davon, ob ein Rezept vorliegt. Bei einer reinen OTC-Bestellung sind
data.doctor_data und data.prescription_file null, und data.prepaid ist 0.data.shipments ist immer vorhanden. Bei der Erstellung ist es ein leeres Array — die Apotheke hat noch nicht versendet. Nachdem die Apotheke Pakete hinzugefügt hat (Apothekenportal oder complete_order mit tracking_links), enthalten spätere pharmacy_order_updated-Zustellungen diese Sendungen.waiting for pharmacy. Die Payload zeigt die Bestellung so, wie sie beim Versand der Zustellung ist; eine pharmacy_order_created-Zustellung kann daher bereits einen späteren Status enthalten.
Mögliche status-Werte: waiting for pharmacy, pending review, on-hold, in-progress, ready_for_pickup, completed, cancelled
Payload-Beispiel
Feldreferenz
shipping_costs_amount und unpaid_shipping_costs_amount sind unterschiedliche Felder — die Garantie „0, niemals null” gilt nur für das erste.data.order.shipping_costs_amount ist immer ein Integer: 0, wenn keine Versandkosten anfallen, niemals null.unpaid_shipping_costs_amount ist eine separate, interne Überschreibung der Versandkosten, die nullable ist und nicht Teil des dokumentierten Webhook-Vertrags ist. Wenn Sie dieses Feld in einer Payload sehen, wenden Sie die Garantie von shipping_costs_amount nicht darauf an: Es kann fehlen oder null sein, und null bedeutet dort nicht „keine Versandkosten”. Verwenden Sie shipping_costs_amount für den Versandkostenabgleich und behandeln Sie unpaid_shipping_costs_amount — sofern Sie es überhaupt auslesen — als optionalen, möglicherweise null-Wert.pharmacy_order_updated
Wird gesendet, wenn sich eine bestehende Apothekenbestellung ändert:- Statusänderungen — im Apothekenportal (einschließlich Sammelaktualisierungen), über die External Pharmacy API (einschließlich Ihrer eigenen Aufrufe von
PATCH .../statusundcomplete_order) oder durch die automatische Statusabfrage bei Ihrem Apothekensystem (zum Beispiel, wenn es die Bestellung als versendet, abgeschlossen oder storniert meldet). - Stornierungen — unabhängig davon, ob die Bestellung von Ihrer Apotheke, vom Admin-Team oder durch die automatische Statusabfrage storniert wird.
- Sendungen — wenn im Apothekenportal eine Sendung manuell erfasst wird, ein Carrier-Label gebucht wird oder Sie die Bestellung über die External Pharmacy API mit
tracking_linksabschließen. Die Label-Buchung sendetpharmacy_order_updatedmit Trackingnummer und Tracking-URL dieser Sendung, auch wenn die Bestellung bereitscompletedist (siehe Sendungen). - Klärfälle — wenn Ihre Apotheke oder das Admin-Team einen Klärfall zur Bestellung eröffnet, wodurch sie auf
on-holdgesetzt wird. - Priorität oder Versandart — wenn Ihre Apotheke die Priorität oder die Versandart der Bestellung im Apothekenportal ändert.
pharmacy_order_created und enthält immer den vollständigen aktuellen Stand der Bestellung, nicht nur den geänderten Teil. Das Feld status enthält den aktuellen Status, und data.shipments listet alle aktuell zur Bestellung gehörenden Sendungen auf (nicht nur die zuletzt hinzugefügte). Was sich geändert hat, ermitteln Sie durch Vergleich mit Ihrem gespeicherten Stand — siehe Ereignisse idempotent verarbeiten.
Es gibt kein separates Ereignis pharmacy_order_shipment_created. Abonnieren Sie pharmacy_order_updated und lesen Sie data.shipments.
Payload-Beispiel
Sendungen
data.shipments ist die Liste der Pakete, die die Apotheke zu dieser Bestellung erfasst hat. Nutzen Sie sie, um Tracking-Daten zu übernehmen, wenn eine Apotheke versendet — einschließlich Teillieferungen (mehrere Pakete).
Wann das Array befüllt ist
- Der Abschluss der Bestellung über
PATCH /v1/external_pharmacy_api/pharmacy_orders/{uid}/complete_ordermittracking_linkslegt eine Sendung an und sendet anschließendpharmacy_order_updated. - Das Hinzufügen einer Sendung im Apothekenportal sendet
pharmacy_order_updated. Das gilt für einen manuellen Tracking-Link und für ein gebuchtes Carrier-Label. Ist die Bestellung bereitscompleted, erhalten Sie ein weiterespharmacy_order_updatedmitstatus: completedund der Sendung indata.shipments, einschließlichtracking_numberundtracking_url. Die Payload enthält alle aktuellen Sendungen, sortiert nachsequence_number. pharmacy_order_createdhat fast immer"shipments": []. Behandeln Sie eine fehlende Tracking-URL bei der Erstellung nicht als Fehler.
- Behandeln Sie
uidals stabile Identität eines Pakets. Ein späterespharmacy_order_updatedkann weitere Einträge hinzufügen; bestehende UIDs bleiben gleich. - Bevorzugen Sie
tracking_urlfür die kundenseitige Sendungsverfolgung.tracking_numberundcarrier_namesind gesetzt, wenn Apotheke oder Carrier sie geliefert haben; beide können bei einer neu angelegten Platzhalter-Sendungnullsein. is_testist nurtrue, wenn das Paket gegen eine Carrier-Sandbox gebucht wurde (kein echter Versand). Ignorieren Sie Testsendungen für die Live-Erfüllung.- Eine stornierte Sendung bleibt im Array.
tracking_numberundtracking_urlsindnull, weil dieses Paket nicht mehr unterwegs ist. return_tracking_numberundreturn_label_expiry(YYYY-MM-DD) sind nur gesetzt, nachdem ein Rücksendeetikett ausgestellt wurde; sonst sind sienull.
Interne Speicherorte der Etikettendateien sind nicht Bestandteil des Webhooks. Verwenden Sie
tracking_url / tracking_number für die Sendungsverfolgung, nicht Speicherpfade.Webhooks auf Organisationsebene
Wenn das Webhook-Abonnement über die Management API (auf Organisationsebene) erstellt wurde, unterscheiden sich Bestellereignisse wie folgt:- Die
sku-Objekte inorder_itemsundfulfillment.itemswerden um Shopify-Bezeichner (shop_variation_id,shop_product_external_id) erweitert. - Ein
fulfillment-Objekt mit Details zur Fulfillment-Bestellung wird hinzugefügt. prescription_fileist nicht enthalten.
Das
fulfillment-Feld und die Shopify-Bezeichner (shop_variation_id, shop_product_external_id) in sku-Objekten sind nur in Webhook-Zustellungen auf Organisationsebene enthalten. Webhooks auf Apothekenebene enthalten diese Felder nicht.pharmacy_sku_stock_updated
Wird gesendet, wenn sich der Lagerbestand einer Apotheken-SKU ändert. Dies umfasst:- Direkte Bestandsaktualisierungen über die Pharmacy-API (
PATCH /v1/.../pharmacy_skus/{uid}/stockoder Inventar-Endpunkte). - Automatische Bestandsreduzierung bei Abschluss einer Apothekenbestellung. Dies wird sowohl beim manuellen Abschluss (über die Apotheken-Oberfläche / API) als auch beim automatischen Abschluss ausgelöst, wenn RxScale über die Statusabfrage-Integration mit dem Backend der Apotheke erkennt, dass die Bestellung versendet oder abgeschlossen wurde. Pro Apotheken-SKU der abgeschlossenen Bestellung wird ein Event emittiert.
Payload-Beispiel
Feldreferenz
Webhooks auf Organisationsebene
Wenn das Webhook-Abonnement über die Management API (auf Organisationsebene) erstellt wurde, enthalten Lagerbestandsereignisse zusätzliche Daten:- Das
sku-Objekt wird um Shopify-Bezeichner (shop_variation_id,shop_product_external_id) erweitert. - Ein
shop_identifier-Feld wird auf derdata-Ebene hinzugefügt.
Das
shop_identifier-Feld und die Shopify-Bezeichner (shop_variation_id, shop_product_external_id) im sku-Objekt sind nur in Webhook-Zustellungen auf Organisationsebene enthalten. Webhooks auf Apothekenebene enthalten diese Felder nicht.appointment_reminder_due
Wird gesendet, wenn eine konfigurierte Terminerinnerung fällig wird. Dieses Ereignis wird ausschließlich an Webhook-Abonnements auf Organisationsebene geliefert.Erinnerungen können für den Patienten auch direkte Aktions-Links enthalten (Beitreten, Umbuchen, Stornieren) — über RxScales eigene E-Mail-/SMS-Inhalte. Die Felder
rebook_allowed und cancel_allowed unten zeigen an, ob diese Aktionen aktuell verfügbar sind — sie sind ausschließlich true, wenn recipient_role gleich patient ist.Payload-Beispiel
Feldreferenz
patient_doctor_meeting_updated
Wird gesendet, wenn eine Patient-Arzt-Besprechung ihren Lebenszyklus-Status ändert. Dieses Ereignis wird ausschließlich an Webhook-Abonnements auf Organisationsebene geliefert (registriert über die Management API). Möglichechange-Werte:
Verwenden Sie
change als maßgeblichen Indikator für das eingetretene Ereignis. status spiegelt den aktuellen Datenbankstatus der Besprechung wider und ist bei On-Demand-Besprechungen null.Payload-Beispiel
Feldreferenz
Abonnieren
Abonnieren Sie über die Management API, um dieses Ereignis zu empfangen:E-Mail-Benachrichtigungen
Unabhängig von Webhooks kann eine Organisation RxScale den Patienten, den Arzt und/oder ihre Admins per E-Mail informieren lassen, wenn eine Besprechung bestätigt, storniert oder verschoben wird. Admins konfigurieren das im Tab “Benachrichtigungen” im Admin-Portal; standardmäßig ist es ausgeschaltet.confirmed ist unabhängig von den beiden anderen Änderungen abonnierbar —
das Aktivieren erfordert nicht, dass auch E-Mails zu Absage oder Verschiebung aktiviert sind.
Am Webhook-Verhalten ändert das nichts. Das Ereignis feuert weiterhin bei jedem oben
aufgeführten Übergang, mit unverändertem Payload — unabhängig davon, ob ein E-Mail-Abonnement
besteht. Der Webhook-Payload selbst bleibt durch dieses Feature unverändert.
Ein Unterschied ist bei der Planung zu beachten: Eine Verschiebung veröffentlicht zwei
Ereignisse — cancelled für die alte und rebooked für die neue Besprechung —, versendet aber
höchstens eine E-Mail, nämlich die zur Verschiebung. Wenn Sie diesen Stream in Ihre eigene
Patientenkommunikation spiegeln, wenden Sie dieselbe Regel an, sonst hört der Patient erst
“storniert” und dann “verschoben”. confirmed ist nicht Teil einer Verschiebung und hat keine
solche Paarung: Es wird einmalig für eine frische Buchung veröffentlicht und löst höchstens eine
Bestätigungs-E-Mail aus.
Zustellung und Idempotenz
Webhooks werden mindestens einmal zugestellt. Ihr Endpunkt sollte Zustellungen als idempotent behandeln und die Kombination ausdata.meeting_uid und data.change als eindeutigen Schlüssel verwenden — erneut zugestellte Events tragen dieselben Werte.
review_request_updated
Wird gesendet, wenn sich eine von Ihnen erstellte Review-Anfrage ändert. Dieses Ereignis wird ausschließlich an Webhook-Abonnements auf Organisationsebene geliefert (registriert über die Management API). Möglichechange-Werte:
Kein Ereignis wird gesendet, wenn die Anfrage erstellt wird (das beantwortet die Antwort auf den
Erstellungsaufruf), oder wenn eine bezahlte Bestellung mit einer Anfrage verknüpft wird, die bereits
storniert oder abgelehnt ist.
Eine Buchung über den Link wird zweimal gemeldet: hier durch
appointment_booked, das den Termin der
Review-Anfrage zuordnet, und wie jeder andere Termin durch
patient_doctor_meeting_updated mit change: "confirmed".
Spätere Änderungen am Termin, etwa eine Absage oder ein Nichterscheinen, meldet nur
patient_doctor_meeting_updated.
Verwenden Sie
change, um zu sehen, was geschehen ist. status ist der Status der Anfrage nach der
Änderung, und beide können sich unterscheiden: assigned und appointment_booked kommen mit dem Status, den die Anfrage
bereits hatte, und ein video_requested nach dem Anlegen der Entwurfsbestellung kommt mit
status: "draft_created".Payload-Beispiel
appointment_booked enthält den gebuchten Termin, und booking ist null:
draft_created enthält stattdessen die Entwurfsbestellung, und booking ist null:
Feldreferenz
Die Payload enthält keinen Patientennamen, keine Kontaktdaten und keine klinischen Inhalte: Der
Patient wird nur über
shop_identifier und shop_customer_id identifiziert.
Der Buchungslink ist an den Arzt gebunden: Der Patient kann nur dessen Zeiten buchen. In Ihren
Shops nimmt RxScale dafür keine Zahlung entgegen. Sobald der Patient bucht, wird der Termin wie
jeder andere über
patient_doctor_meeting_updated gemeldet,
und für die Review-Anfrage über appointment_booked, das seine meeting_uid enthält.Abonnieren
Abonnieren Sie über die Management API, um dieses Ereignis zu empfangen:POST /v1/management/notification-subscriptions/test
und "event_type": "review_request_updated". Eine Apothekenbestellung ist dafür nicht nötig.
Zustellung und Idempotenz
Jede Payload enthält den Stand der Anfrage zum Zeitpunkt der Änderung, nicht zum Zeitpunkt der Zustellung. Webhooks werden mindestens einmal zugestellt, und eine wiederholte Zustellung enthält dieselben Daten mit einem neuentimestamp. Richten Sie Ihre Verarbeitung nach diesen Regeln aus:
assignedkann für dieselbe Anfrage mehrmals auftreten, jeweils mit einem anderen Arzt.video_requestedtritt nur erneut auf, wenn der Arzt den Link ersetzt hat. Das ist erst möglich, wenn der vorige Link ungenutzt abgelaufen ist oder sein Termin nicht mehr besteht.appointment_bookedtritt einmal je gebuchtem Termin auf: Nach einem ersetzten Link sendet eine zweite Buchung ein zweites, mit einer anderenappointment.meeting_uid. Verwenden Siereview_request_uidundchangenicht als eindeutigen Schlüssel. Sorgen Sie stattdessen dafür, dass die zweimalige Verarbeitung einer Payload unschädlich ist, indem Sie dem Patienten zum Beispiel einen Buchungslink nur senden, wenn er sich von dem bereits gesendeten unterscheidet.- Zustellungen können in anderer Reihenfolge eintreffen, zum Beispiel wenn eine Zustellung
wiederholt wird. Ein Endstatus (
completed,declined,cancelled) ändert sich nie wieder. Ignorieren Sie daher eine Payload mit einem offenen Status, sobald Sie einen Endstatus erfasst haben. - Im Zweifel rufen Sie den aktuellen Stand mit
GET /v1/management/review-requests/{review_request_uid}ab.