> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rxscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Webhooks für Echtzeit-Benachrichtigungen zu Apothekenbestellungen und Bestandsänderungen registrieren

# Webhooks (External Pharmacy API)

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

<Note>
  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`.
</Note>

## Webhooks auflisten

```bash theme={null}
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.

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/external_pharmacy_api/webhooks/" \
  -H "X-API-Key: your-api-key-here"
```

### Antwort

```json theme={null}
[
  {
    "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

```bash theme={null}
POST /v1/external_pharmacy_api/webhooks/
```

### Anfragekörper

<ParamField body="target" type="string" required>
  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.
</ParamField>

<ParamField body="notification_type" type="string" required>
  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.
</ParamField>

<ParamField body="pharmacy_uid" type="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.
</ParamField>

<ParamField body="header_key" type="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).
</ParamField>

<ParamField body="header_value" type="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.
</ParamField>

```bash theme={null}
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)

```json theme={null}
{
  "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"
}
```

<Warning>
  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](/de/webhooks/security).
</Warning>

### 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](/de/webhooks/security#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

```bash theme={null}
DELETE /v1/external_pharmacy_api/webhooks/{subscription_uid}
```

```bash theme={null}
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](/de/webhooks/events).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.