Skip to main content

​
Webhooks

Mit Webhooks erhalten Sie Echtzeit-HTTP-Benachrichtigungen, wenn Ereignisse in RxScale auftreten. Anstatt regelmäßig nach Änderungen abzufragen, registrieren Sie eine Webhook-URL, und RxScale sendet Ihnen bei jedem Ereignis eine POST-Anfrage.

​
Funktionsweise von Webhooks

  1. Registrieren Sie ein Webhook-Abonnement mit Ihrer Ziel-URL und dem gewünschten Ereignistyp.
  2. Empfangen Sie POST-Anfragen an Ihre URL, wenn Ereignisse eintreten.
  3. Überprüfen Sie die Webhook-Signatur, um die Authentizität der Anfrage sicherzustellen.
  4. Antworten Sie mit einem 2xx-Statuscode, um den Empfang zu bestätigen.

​
Webhook-Payload-Format

Alle Webhook-Payloads folgen derselben Envelope-Struktur:

​
Ereignisse idempotent verarbeiten

Bestell- und Bestandsereignisse (pharmacy_order_created, pharmacy_order_updated, pharmacy_sku_stock_updated) beschreiben keine Änderung. Jede Payload ist ein vollständiger Schnappschuss der Apothekenbestellung bzw. der Apotheken-SKU, erstellt in dem Moment, in dem die Zustellung versendet wird. Es gibt keine Ereignis-ID. Daraus folgt:
  • Derselbe Stand kann Sie mehrfach erreichen — zum Beispiel, wenn eine Zustellung wiederholt wird oder mehrere Änderungen kurz nacheinander erfolgen.
  • pharmacy_order_updated kann vor dem pharmacy_order_created derselben Bestellung eintreffen — zum Beispiel, wenn die erste Zustellung von pharmacy_order_created fehlgeschlagen ist und später wiederholt wird.
  • pharmacy_order_updated gibt nicht an, was sich geändert hat.
Richten Sie Ihre Verarbeitung an diesen Regeln aus:
  1. Verwenden Sie data.uid als Schlüssel und legen Sie den Datensatz an oder aktualisieren Sie ihn (Upsert) — unabhängig davon, welches Ereignis zuerst eintrifft.
  2. Behandeln Sie jede Payload als aktuellen Gesamtstand und ersetzen Sie Ihre gespeicherte Kopie damit. Was sich geändert hat, ermitteln Sie durch Vergleich mit Ihrem gespeicherten Stand — zum Beispiel status oder shipments.
  3. Überspringen Sie eine Payload, deren data.updated_at älter ist als der gespeicherte Wert. Es handelt sich um einen älteren Stand, der verspätet eingetroffen ist.
  4. Stellen Sie sicher, dass die zweimalige Verarbeitung derselben Payload keinen Schaden anrichtet.
  5. Deduplizieren Sie nicht anhand von timestamp. Der Wert wird pro Zustellversuch gesetzt: Eine Wiederholung trägt einen neuen Wert, während zwei verschiedene Aktualisierungen, die in derselben Sekunde versendet werden, denselben Wert haben.
appointment_reminder_due und patient_doctor_meeting_updated enthalten die Daten zum Zeitpunkt des Ereignisses, keinen beim Versand erstellten Schnappschuss. Für Besprechungsereignisse siehe Zustellung und Idempotenz.

​
Webhooks registrieren

Sie können Webhooks über folgende Wege registrieren:
  • Apothekenportal — Navigieren Sie zum API-Zugang in der Seitenleiste. Wenn Sie mehrere Apothekengruppen verwalten, wählen Sie die Gruppe aus dem Dropdown oben auf der Seite.
  • External Pharmacy API — POST /v1/external_pharmacy_api/webhooks/
  • Management API — POST /v1/management/notification-subscriptions/
Jede Registrierung gibt in der Erstellungsantwort ein webhook_secret zurück, egal ob Sie über die External Pharmacy API, das Apothekenportal oder die Management API registrieren. Es wird nur einmal angezeigt; bewahren Sie es sicher auf, da Sie es zur Überprüfung der Payload-Signaturen benötigen (siehe Sicherheit). Abonnements über die Management API können zusätzlich einen von Ihnen konfigurierten benutzerdefinierten Request-Header senden (header_key / header_value), zum Beispiel einen API-Schlüssel, den Ihr Endpoint bereits prüft.

​
Wiederholungsrichtlinie

​
Erfolgreiche und fehlgeschlagene Zustellungen

Eine Zustellung gilt als erfolgreich, sobald Ihr Endpoint mit einem beliebigen 2xx-Statuscode antwortet — auch wenn Ihre eigene Verarbeitung der Payload danach fehlschlägt. Speichern Sie die Payload zuerst, antworten Sie und verarbeiten Sie aufwändige Arbeit anschließend asynchron. Eine Zustellung gilt als fehlgeschlagen, wenn:
  • Ihr Endpoint mit einem anderen Statuscode antwortet — auch mit 3xx (Weiterleitungen werden nicht verfolgt) und mit jedem 4xx, etwa 413 Payload Too Large;
  • Ihr Endpoint nicht innerhalb von 30 Sekunden antwortet;
  • keine Verbindung aufgebaut werden kann oder der TLS-Handshake fehlschlägt (zum Beispiel wegen eines ungültigen Zertifikats).
Löst Ihre Ziel-URL zum Zeitpunkt der Zustellung auf eine private oder interne IP-Adresse auf, wird die Zustellung verweigert und nicht wiederholt.

​
Wiederholungen

Fehlgeschlagene Zustellungen werden mit exponentiellem Backoff wiederholt: Die erste Wiederholung erfolgt nach etwa 10 Sekunden, der Abstand wächst auf höchstens etwa 10 Minuten zwischen zwei Versuchen. Nach insgesamt 5 Versuchen wird die Zustellung verworfen. Es gibt keine Dead-Letter-Queue und keine Möglichkeit, eine verworfene Zustellung erneut auszulösen. Jeder Versuch erstellt die Payload neu, daher enthält eine Wiederholung den aktuellen Stand und einen neuen timestamp. Wurden Zustellungen verworfen — zum Beispiel nach einem Ausfall Ihres Endpoints —, gleichen Sie Ihre Daten über die External Pharmacy API ab:
  • Listen Sie Bestellungen mit GET /v1/external_pharmacy_api/pharmacy_orders/ auf. Die Filter start_date und end_date beziehen sich auf den Erstellungszeitpunkt der Bestellung.
  • Rufen Sie den aktuellen Stand einer Bestellung mit GET /v1/external_pharmacy_api/pharmacy_orders/{pharmacy_order_uid} ab. Die Antwort wird aus denselben Daten erstellt wie die Webhook-Payload.
  • Für Lagerbestände listen Sie Ihre SKUs mit GET /v1/external_pharmacy_api/pharmacy_skus/ auf.
Details finden Sie unter Apothekenbestellungen und Apotheken-SKUs. RxScale deaktiviert ein Abonnement nie wegen fehlgeschlagener Zustellungen. Ein Abonnement bleibt aktiv, bis Sie es löschen.

​
Zustellprotokolle

Jeder Zustellversuch für die Abonnements Ihrer Apothekengruppe — erfolgreich oder fehlgeschlagen — wird im Apothekenportal unter API-Zugang → Webhook-Zustellprotokolle mit dem Statuscode der Antwort bzw. dem Fehler angezeigt. Eine verworfene Zustellung erscheint dort als endgültiger Fehlschlag.

​
Payload-Größe

Es gibt keine feste Größenbeschränkung, und Payloads werden nie gekürzt. Bei Abonnements, die über die External Pharmacy API oder das Apothekenportal registriert wurden, enthalten Bestell-Payloads das signierte Rezept-PDF direkt, Base64-kodiert in data.prescription_file.content_base64 — nie als Link. Es ist ein PDF pro Bestellung, das in pharmacy_order_created und in jedem pharmacy_order_updated mitgesendet wird. Bei Bestellungen, die nur rezeptfreie Produkte enthalten, ist prescription_file null. Zustellungen auf Organisationsebene (Management API) enthalten prescription_file nicht. Payloads sind typischerweise einige hundert Kilobyte groß, hochgeladene oder extern signierte Rezept-PDFs können aber deutlich größer sein. Konfigurieren Sie Ihren Endpoint — und vorgeschaltete Proxys oder Frameworks — so, dass er Anfragekörper von mindestens 10 MB annimmt. Eine 413-Antwort ist eine fehlgeschlagene Zustellung wie jede andere: Sie wird wiederholt und anschließend verworfen.