Webhooki

Webhooki umożliwiają Cost+ powiadamianie Twojego serwera w czasie rzeczywistym za każdym razem, gdy zmieni się status zamówienia. Zamiast cyklicznie odpytywać API, podajesz URL, a Cost+ wysyła żądanie HTTP POST, gdy pojawi się aktualizacja.

Jak działają webhooki

Określasz webhook_url podczas tworzenia zamówienia lub konfigurujesz domyślny URL webhooka na poziomie projektu.
Gdy status zamówienia się zmieni (np. z new na completed), Cost+ wysyła żądanie POST na Twój URL webhooka.
Twój serwer odbiera webhook, a następnie wywołuje API Cost+, aby pobrać pełne szczegóły zamówienia.
Aktualizujesz swój system na podstawie zweryfikowanego statusu zamówienia.

Nigdy nie ufaj samej treści webhooka do realizacji zamówienia. Zawsze weryfikuj status zamówienia, wykonując żądanie GET /v1/orders/{id}/ po otrzymaniu webhooka. Webhook jest mechanizmem powiadomień, a nie źródłem prawdy.

Treść webhooka

Treść webhooka to obiekt JSON zawierający typ zdarzenia i identyfikator zamówienia:

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

Pole	Opis
`event`	Typ zdarzenia. Obecnie `status_changed` dla aktualizacji zamówień.
`order_id`	Unikalny identyfikator zamówienia, którego status się zmienił.
`project_id`	Projekt, do którego należy zamówienie.

Ustawianie URL webhooka

URL webhooka możesz ustawić na dwa sposoby:

Dla pojedynczego zamówienia

Dołącz pole webhook_url podczas tworzenia zamówienia:

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

Domyślny dla projektu

Skonfiguruj domyślny URL webhooka w panelu Cost+ w ustawieniach projektu. Ten URL będzie używany dla wszystkich zamówień, które nie określają własnego webhook_url.

Nawet jeśli masz domyślny URL na poziomie projektu, możesz go nadpisać dla poszczególnych zamówień, dołączając webhook_url w żądaniu tworzenia zamówienia.

Logika ponowień

Jeśli Twój serwer nie odpowie kodem statusu 2xx, Cost+ ponowi dostarczenie webhooka:

Maksymalna liczba ponowień: 10 prób
Interwał ponowień: 2 minuty między każdą próbą
Limit czasu pierwszej próby: 4 sekundy
Limit czasu kolejnych prób: 10 sekund

Jeśli wszystkie 10 prób ponowień się nie powiedzie, webhook jest oznaczany jako nieudany. Status zamówienia możesz nadal pobrać w dowolnym momencie, odpytując API.

Upewnij się, że Twój punkt końcowy webhooka odpowiada szybko (w ciągu 4 sekund dla pierwszej próby). Wszelkie długotrwałe przetwarzanie wykonuj asynchronicznie po zwróceniu odpowiedzi 200 OK.

Najlepsze praktyki

Zawsze weryfikuj przez API. Po otrzymaniu webhooka wywołaj GET /v1/orders/\{order_id\}/, aby potwierdzić aktualny status przed podjęciem działań, takich jak wysyłka towarów lub przyznanie dostępu.
Zwracaj 200 szybko. Potwierdź webhook odpowiedzią 200 natychmiast i przetwarzaj zamówienie asynchronicznie, aby uniknąć przekroczeń limitu czasu.
Obsługuj duplikaty. Twój punkt końcowy webhooka może otrzymać to samo zdarzenie więcej niż raz. Upewnij się, że Twoja logika przetwarzania jest idempotentna.
Używaj HTTPS. Zawsze używaj adresu URL HTTPS dla punktu końcowego webhooka, aby zapewnić bezpieczną transmisję danych.
Loguj treści webhooków. Przechowuj przychodzące dane webhooków do celów debugowania i audytu.

Powiązane punkty końcowe

Utwórz zamówienie — ustaw webhook_url dla pojedynczego zamówienia
Zaktualizuj zamówienie — zaktualizuj URL webhooka na istniejącym zamówieniu
Schematy zdarzeń webhooków — format danych dla OrderStatusChangedEvent i TransactionStatusChangedEvent

On this page