Webhooks

Webhooks ermöglichen es Cost+, Ihren Server in Echtzeit zu benachrichtigen, wenn sich der Status einer Bestellung ändert. Anstatt die API abzufragen, geben Sie eine URL an, und Cost+ sendet einen HTTP-POST-Request an diese, wenn es ein Update gibt.

So funktionieren Webhooks

Sie geben eine webhook_url beim Erstellen einer Bestellung an oder konfigurieren eine Standard-Webhook-URL auf Projektebene.
Wenn sich der Bestellungsstatus ändert (z. B. von new zu completed), sendet Cost+ einen POST-Request an Ihre Webhook-URL.
Ihr Server empfängt den Webhook und ruft dann die Cost+ API auf, um die vollständigen Bestellungsdetails abzurufen.
Sie aktualisieren Ihr System basierend auf dem verifizierten Bestellungsstatus.

Vertrauen Sie niemals dem Webhook-Payload allein, um eine Bestellung auszuführen. Verifizieren Sie den Bestellungsstatus immer durch einen GET /v1/orders/{id}/-Request nach dem Empfang eines Webhooks. Der Webhook ist ein Benachrichtigungsmechanismus, keine Quelle der Wahrheit.

Webhook-Payload

Der Webhook-Body ist ein JSON-Objekt mit dem Ereignistyp und der Bestell-ID:

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}

Feld	Beschreibung
`event`	Der Typ des Ereignisses. Derzeit `status_changed` für Bestellungsaktualisierungen.
`order_id`	Der eindeutige Bezeichner der Bestellung, deren Status sich geändert hat.
`project_id`	Das Projekt, zu dem die Bestellung gehört.

Webhook-URL festlegen

Sie können die Webhook-URL auf zwei Arten festlegen:

Pro Bestellung

Geben Sie das Feld webhook_url beim Erstellen einer Bestellung an:

{
  "currency": "EUR",
  "amount": 1295,
  "webhook_url": "https://www.example.com/webhook"
}

Projektstandard

Konfigurieren Sie eine Standard-Webhook-URL in Ihrem Cost+ Dashboard unter den Projekteinstellungen. Diese URL wird für alle Bestellungen verwendet, die keine eigene webhook_url angeben.

Auch wenn Sie einen projektweiten Standard haben, können Sie diesen pro Bestellung überschreiben, indem Sie webhook_url im Bestellerstellungs-Request angeben.

Wiederholungslogik

Wenn Ihr Server nicht mit einem 2xx-Statuscode antwortet, wiederholt Cost+ die Webhook-Zustellung:

Maximale Wiederholungen: 10 Versuche
Wiederholungsintervall: 2 Minuten zwischen jedem Versuch
Timeout beim ersten Versuch: 4 Sekunden
Timeout bei nachfolgenden Versuchen: 10 Sekunden

Wenn alle 10 Wiederholungsversuche fehlschlagen, wird der Webhook als fehlgeschlagen markiert. Sie können den Bestellungsstatus jederzeit durch Abfrage der API abrufen.

Stellen Sie sicher, dass Ihr Webhook-Endpunkt schnell antwortet (innerhalb von 4 Sekunden beim ersten Versuch). Führen Sie langwierige Verarbeitungen asynchron durch, nachdem Sie eine 200 OK-Antwort zurückgegeben haben.

Best Practices

Immer über die API verifizieren. Rufen Sie nach dem Empfang eines Webhooks GET /v1/orders/\{order_id\}/ auf, um den aktuellen Status zu bestätigen, bevor Sie Maßnahmen wie den Versand von Waren oder die Gewährung von Zugang ergreifen.
Schnell 200 zurückgeben. Bestätigen Sie den Webhook sofort mit einer 200-Antwort und verarbeiten Sie die Bestellung asynchron, um Timeouts zu vermeiden.
Duplikate behandeln. Ihr Webhook-Endpunkt kann dasselbe Ereignis mehrfach empfangen. Stellen Sie sicher, dass Ihre Verarbeitungslogik idempotent ist.
HTTPS verwenden. Verwenden Sie immer eine HTTPS-URL für Ihren Webhook-Endpunkt, um die sichere Übertragung des Payloads zu gewährleisten.
Webhook-Payloads protokollieren. Speichern Sie eingehende Webhook-Daten für Debugging- und Prüfungszwecke.