Webhooks¶

PharmaOne kann JSON per POST an Ihre HTTPS-URL senden, wenn abonnierte Ereignisse eintreten.

Konfiguration in Manager → Org Settings → Integrations → Webhook subscriptions (max. 5 pro Org).

Eingehend vs. ausgehend

Webhooks sind ausgehend von PharmaOne zu Ihrem Server. Sie sind nicht in der OpenAPI-Pfadliste — dokumentieren Sie Ihren Empfänger separat.

Abonnement einrichten¶

Abonnement mit HTTPS-URL anlegen (muss 2xx zurückgeben).
Ereignistypen wählen (Checkboxen in der UI).
Signing secret speichern — wird einmal angezeigt.

Mit Send test event in der Manager-UI den Endpunkt prüfen.

Zustellungs-Request¶

POST https://your-server.example/webhooks/pharmaone
Content-Type: application/json
X-PharmaOne-Event: order_status_updated
X-PharmaOne-Delivery-Id: 3c0d62fb-c683-4644-a74c-9e3ad3d52622
X-PharmaOne-Signature: sha256=<hmac-sha256-hex-of-raw-body>

Header	Beschreibung
`Content-Type`	`application/json`
`X-PharmaOne-Event`	Ereignis-Slug
`X-PharmaOne-Delivery-Id`	Eindeutige Zustell-ID (Idempotenz)
`X-PharmaOne-Signature`	`sha256=` + HMAC-SHA256-Hex des Rohbodys

Payload-Form¶

{
  "id": "uuid-event-id",
  "org_id": "org1",
  "event_type": "order_status_updated",
  "title": "Order status updated",
  "description": "Order ORD_20260605_abc123 updated via external API",
  "metadata": {
    "order_id": "ORD_20260605_abc123",
    "old_status": "awaiting_packing",
    "new_status": "ready_pickup"
  },
  "created_at": "2026-06-05T12:00:00Z"
}

Signatur prüfen (Python)¶

import hmac
import hashlib

def verify(secret: str, raw_body: bytes, header_signature: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(header_signature, expected)

Abonnierbare Ereignistypen¶

Bestellungen¶

Ereignis	Auslöser
`order_created`	Neue Bestellung
`order_updated`	Bestellfelder aktualisiert
`order_status_updated`	Status oder Flags geändert (inkl. externem API-PATCH)
`order_marked_paid`	Als bezahlt markiert
`order_deleted`	Bestellung gelöscht

Bestellanfragen¶

Ereignis	Auslöser
`order_request_submitted`	Externe Bestellanfrage eingegangen
`order_request_approved`	Von Mitarbeitern freigegeben
`order_request_deleted`	Anfrage gelöscht

Rezepte¶

Ereignis	Auslöser
`prescription_approved`	Rezept freigegeben
`paperless_signature_completed`	QES-Unterschrift abgeschlossen

Produkte & Bestand¶

Ereignis	Auslöser
`product_created`	Produkt angelegt
`product_updated`	Produkt aktualisiert
`product_deleted`	Produkt gelöscht
`low_stock`	Bestand unter Schwellwert
`out_of_stock`	Bestand null

Zahlungen¶

Ereignis	Auslöser
`payment_link_created`	Zahlungslink erzeugt

Wiederholungen¶

Bis zu 3 Zustellversuche mit Backoff.
Fehlgeschlagene Zustellungen pro Abonnement protokolliert (in Manager-UI sichtbar).
Schnell 2xx zurückgeben; Verarbeitung ggf. asynchron.

Lokales Testen¶

Lokalen Empfänger per Tunnel (z. B. ngrok) exponieren und die HTTPS-URL beim Anlegen des Abonnements in Manager verwenden.

Beispiel: Bestellanfrage eingereicht¶

{
  "id": "3c0d62fb-c683-4644-a74c-9e3ad3d52622",
  "org_id": "org1",
  "event_type": "order_request_submitted",
  "title": "Order request submitted",
  "description": "External order request 7b8e6bef-… received",
  "metadata": {
    "order_request_id": "7b8e6bef-75e0-40ea-8168-de30d1329972",
    "external_reference": "doc-example",
    "shop_id": "shop1",
    "source": "api-docs"
  },
  "created_at": "2026-06-06T00:27:41Z"
}