Webhooks (External Pharmacy API)

Registrieren Sie Webhooks, um Echtzeitbenachrichtigungen zu erhalten, wenn Apothekenbestellungen erstellt oder aktualisiert werden oder wenn sich Lagerbestände ändern.

Zum Auflisten von Webhooks benötigen Sie die Berechtigung webhooks_read, zum Registrieren und Entfernen die Berechtigung webhooks_write. Ein Schlüssel ohne die erforderliche Berechtigung erhält 403.

Webhooks auflisten

GET /v1/external_pharmacy_api/webhooks/

Gibt die Webhook-Abonnements Ihrer Apothekengruppe zurück. Mit einem Einzelapotheken-API-Schlüssel enthält die Liste nur Abonnements, die auf diese Apotheke beschränkt sind — gruppenweite Abonnements, etwa solche aus dem Apothekenportal, werden nicht aufgeführt.

curl -X GET "https://api.rxscale.com/v1/external_pharmacy_api/webhooks/" \
  -H "X-API-Key: your-api-key-here"

Antwort

[
  {
    "uid": "sub-abc123",
    "target": "https://your-system.com/webhooks/rxscale",
    "notification_type": "pharmacy_order_created",
    "pharmacy_uid": null,
    "header_key": "X-Custom-Auth"
  }
]

Das webhook_secret und der Wert des benutzerdefinierten Headers werden nie zurückgegeben. Die Antwort kann weitere Felder enthalten; ignorieren Sie Felder, die Sie nicht verwenden.

Webhook registrieren

POST /v1/external_pharmacy_api/webhooks/

Anfragekörper

string

erforderlich

Die URL, die die Webhook-Anfragen empfängt. Sie muss eine https://-URL sein, deren Host auf eine öffentliche IP-Adresse auflöst. localhost, *.local-Hosts, private oder interne IP-Adressen und Hosts, die sich nicht auflösen lassen, werden mit 400 abgelehnt.

string

erforderlich

Das zu abonnierende Ereignis: pharmacy_order_created, pharmacy_order_updated oder pharmacy_sku_stock_updated. Jedes Abonnement umfasst genau einen Ereignistyp; registrieren Sie daher ein Abonnement pro Ereignis, das Sie empfangen möchten.

string

Beschränkt das Abonnement auf eine Apotheke.

Mit einem Einzelapotheken-API-Schlüssel ist das Abonnement immer auf die Apotheke dieses Schlüssels beschränkt, und das Feld wird ignoriert.
Mit einem gruppenweiten API-Schlüssel muss die Apotheke zu Ihrer Apothekengruppe gehören, sonst schlägt die Anfrage mit 400 fehl. Lassen Sie das Feld weg, um ein gruppenweites Abonnement zu erstellen, das die Ereignisse aller Apotheken der Gruppe erhält.

string

Name eines benutzerdefinierten HTTP-Headers, den RxScale bei jeder Zustellung mitsendet — zum Beispiel zur Authentifizierung an Ihrem Endpoint. 1–255 Zeichen. Senden Sie ihn zusammen mit header_value. Muss ein gültiger HTTP-Headername sein: Buchstaben, Ziffern, Bindestriche und Unterstriche (zum Beispiel X-Api-Key), ohne Leerzeichen oder Doppelpunkte. Die reservierten Namen Content-Type, X-Webhook-Event, X-Webhook-Signature, X-Webhook-Test sowie verbindungsbezogene Header wie Host, Content-Length, Transfer-Encoding, Connection und Proxy-Authorization werden abgelehnt (unabhängig von Groß-/Kleinschreibung).

string

Wert des benutzerdefinierten Headers. 1–4096 Zeichen. Erforderlich, wenn header_key gesetzt ist, und andernfalls wegzulassen. Er wird verschlüsselt gespeichert und nie zurückgegeben.

curl -X POST "https://api.rxscale.com/v1/external_pharmacy_api/webhooks/" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://your-system.com/webhooks/rxscale",
    "notification_type": "pharmacy_order_created",
    "header_key": "X-Custom-Auth",
    "header_value": "my-secret-token"
  }'

Antwort (201 Created)

{
  "uid": "sub-abc123",
  "target": "https://your-system.com/webhooks/rxscale",
  "notification_type": "pharmacy_order_created",
  "pharmacy_uid": null,
  "header_key": "X-Custom-Auth",
  "webhook_secret": "EXAMPLE_webhook_secret_returned_only_once"
}

Das webhook_secret wird nur in dieser Antwort zurückgegeben und kann später nicht abgerufen werden. Speichern Sie es sicher — Sie benötigen es zur Verifizierung von Webhook-Signaturen. Weitere Informationen finden Sie unter Webhook-Sicherheit.

Dasselbe Abonnement erneut registrieren

Ein Abonnement wird durch notification_type, target und pharmacy_uid bestimmt. Wenn Sie dieselbe Kombination erneut registrieren — auch nach dem Löschen —, behält RxScale die bestehende uid bei, stellt ein neues webhook_secret aus (das alte funktioniert sofort nicht mehr) und ersetzt den benutzerdefinierten Header. Lassen Sie header_key und header_value weg, wird der benutzerdefinierte Header entfernt. So können Sie das Secret rotieren — siehe Secret rotieren.

Fehler

Status	Ursache
`400`	Ungültiger Anfragekörper — zum Beispiel ein `target`, das keine öffentliche HTTPS-URL ist, ein unbekannter `notification_type`, `header_key` ohne `header_value`, ein reservierter Header-Name oder eine `pharmacy_uid` außerhalb Ihrer Apothekengruppe
`403`	Dem API-Schlüssel fehlt die Berechtigung `webhooks_write`

Webhook entfernen

DELETE /v1/external_pharmacy_api/webhooks/{subscription_uid}

curl -X DELETE "https://api.rxscale.com/v1/external_pharmacy_api/webhooks/sub-abc123" \
  -H "X-API-Key: your-api-key-here"

Gibt bei Erfolg 204 No Content zurück. Für das Abonnement werden danach keine Zustellungen mehr gesendet, auch keine Wiederholungen früherer Ereignisse. Gibt 404 zurück, wenn das Abonnement nicht existiert oder für Ihren API-Schlüssel nicht sichtbar ist. Ein Einzelapotheken-API-Schlüssel kann nur Abonnements entfernen, die auf seine Apotheke beschränkt sind.

Wie Ereignisse Ihre Abonnements erreichen

Ein Ereignis für eine Apotheke wird an jedes Abonnement der Apothekengruppe zugestellt, das entweder gruppenweit ist (pharmacy_uid ist null) oder auf diese Apotheke beschränkt ist.

Wenn Sie für dasselbe Ereignis sowohl ein gruppenweites als auch ein apothekenspezifisches Abonnement haben, erhalten Sie jedes Ereignis dieser Apotheke zweimal — einmal pro Abonnement.
Im Apothekenportal registrierte Abonnements sind immer gruppenweit.
Jedes Abonnement hat ein eigenes webhook_secret, und Zustellungen geben nicht an, zu welchem Abonnement sie gehören. Verwenden Sie für jedes Abonnement eine eigene Ziel-URL (zum Beispiel einen anderen Pfad), damit Sie immer wissen, mit welchem Secret Sie prüfen müssen.

Verfügbare Ereignistypen

Ereignistyp	Beschreibung
`pharmacy_order_created`	Eine neue Apothekenbestellung wurde erstellt
`pharmacy_order_updated`	Eine bestehende Bestellung hat sich geändert, einschließlich Statusaktualisierungen und von der Apotheke hinzugefügter Sendungen
`pharmacy_sku_stock_updated`	Der Lagerbestand eines Ihrer SKUs hat sich geändert

Vollständige Details zu den Payloads finden Sie unter Webhook-Ereignisse.

Erste Schritte

Externe Apotheken-API

Management-API

Scheduling API

Öffentliche API

Patienten-API

Anamnese-API

Webhooks

Anleitungen

Webhooks

Webhooks (External Pharmacy API)

Webhooks auflisten

Antwort

Webhook registrieren

Anfragekörper

Antwort (201 Created)

Dasselbe Abonnement erneut registrieren

Fehler

Webhook entfernen

Wie Ereignisse Ihre Abonnements erreichen

Verfügbare Ereignistypen

​Webhooks (External Pharmacy API)

​Webhooks auflisten

​Antwort

​Webhook registrieren

​Anfragekörper

​Antwort (201 Created)

​Dasselbe Abonnement erneut registrieren

​Fehler

​Webhook entfernen

​Wie Ereignisse Ihre Abonnements erreichen

​Verfügbare Ereignistypen

Webhooks (External Pharmacy API)

Webhooks auflisten

Antwort

Webhook registrieren

Anfragekörper

Antwort (201 Created)

Dasselbe Abonnement erneut registrieren

Fehler

Webhook entfernen

Wie Ereignisse Ihre Abonnements erreichen

Verfügbare Ereignistypen