Webhook-Ereignisse

Erfahren Sie mehr über die in der Curosa-API verfügbaren Webhook-Ereignisse und wie man mit ihnen umgeht.

Übersicht

Webhooks ermöglichen es Ihnen, Benachrichtigungen in Echtzeit zu erhalten, wenn Ereignisse in der Curosa-Plattform auftreten. Wenn ein Ereignis eintritt, senden wir eine HTTP-POST-Anfrage an jede aktive Webhook-URL, die für dieses Ereignis abonniert ist. Dies ermöglicht es Ihnen, Ihre Systeme mit Curosa zu integrieren und automatisch auf Ereignisse zu reagieren.

Webhook-Zustellung

Wenn ein Ereignis eintritt, senden wir eine einzelne HTTP-POST-Anfrage an jede Webhook-URL, die aktiv und für dieses Ereignis abonniert ist.

Anfrageformat

Eigenschaft	Wert
Methode	`POST`
URL	Die von Ihnen konfigurierte Webhook-URL
Header	`Content-Type: application/json`
Body	JSON-Objekt (siehe unten)

Struktur des Anfrage-Bodys

Jeder Webhook-Anfrage-Body folgt dieser einheitlichen Struktur:

Feld	Typ	Beschreibung
`event`	string	Ereignis-ID (z. B. `NewOrderCreated`). Verwenden Sie diese, um das Ereignis weiterzuleiten oder zu verarbeiten.
`data`	object	Ereignisspezifische Nutzlast. Die Struktur hängt vom `event`-Typ ab (siehe Ereignisdetails unten).
`timestamp`	string	ISO 8601-Datum/Uhrzeit, wann die Anfrage gesendet wurde (z. B. `2026-02-05T14:30:00.000000Z`).

Verfügbare Ereignisse

NewOrderCreated

Wird gesendet, wenn eine neue Kundenbestellung erstellt wird, die Ihre Produkte enthält. Pro Bestellung wird ein Webhook-Aufruf gesendet (eine Bestellungsgruppe mit mehreren Lieferantenbestellungen löst also einen Aufruf pro Lieferantenbestellung aus).

Ereignis-ID: "NewOrderCreated"

Datenstruktur:

Pfad	Typ	Beschreibung
`data.order`	object	Die erstellte Bestellung
`data.order.id`	integer	Interne Bestell-ID
`data.order.order_number`	string \| null	Menschenlesbare Bestellnummer (falls gesetzt)
`data.order.status`	string	Bestellstatus (z. B. `pending`)
`data.order.allocation_status`	string	Lagerzuteilungsstatus (z. B. `unallocated`, `allocated`)
`data.order.currency`	string	Währungscode (z. B. `GBP`)
`data.order.items_cost_total`	number	Gesamtkosten der Artikel in der Bestellung
`data.order.created_at`	string \| null	ISO 8601-Datum/Uhrzeit der Bestellerstellung
`data.customer`	object \| null	Mit der Bestellung verknüpfter Kunde, oder `null`, falls nicht gesetzt
`data.customer.id`	integer	Interne Kunden-ID
`data.customer.name`	string	Anzeigename des Kunden

Beispiel-Anfrage:

{
  "event": "NewOrderCreated",
  "data": {
    "order": {
      "id": 12345,
      "order_number": "ORD-2026-001234",
      "status": "pending",
      "allocation_status": "unallocated",
      "currency": "GBP",
      "items_cost_total": 150.00,
      "created_at": "2026-02-05T14:30:00.000000Z"
    },
    "customer": {
      "id": 678,
      "name": "Jane Smith"
    }
  },
  "timestamp": "2026-02-05T14:30:01.000000Z"
}

Webhook-Zustellung und Wiederholungen

Asynchrone Zustellung: Webhooks werden asynchron gesendet (Warteschlange). Eine leichte Verzögerung nach dem Eintreten des Ereignisses ist normal.
Zustellungsstatus: Der Zustellungsstatus (z. B. letzter Erfolg oder Fehler) wird derzeit nicht in der Benutzeroberfläche angezeigt.
Wiederholungsverhalten: Wenn Ihr Endpunkt einen Nicht-2xx-Statuscode zurückgibt oder wir ihn nicht erreichen können (z. B. Timeout), protokollieren wir den Fehler und versuchen es gegebenenfalls gemäß unserer Warteschlangenkonfiguration erneut.

Umgang mit unbekannten Ereignissen

In Zukunft können weitere Ereignisse hinzugefügt werden. Ihr Webhook-Endpunkt sollte so konzipiert sein, dass er:

Unbekannte event-Werte problemlos ignoriert oder
unbekannte Ereignisse zu Support- und Debugging-Zwecken protokolliert.

Dies stellt sicher, dass Ihre Integration stabil bleibt, wenn neue Ereignistypen in die API eingeführt werden.