Webhooks

Webhooks leidžia Cost+ informuoti jūsų serverį realiu laiku, kai pasikeičia užsakymo būsena. Užuot periodiškai tikrinę API, jūs pateikiate URL, ir Cost+ siunčia HTTP POST užklausą į jį kiekvieną kartą, kai yra atnaujinimas.

Kaip veikia Webhooks

Nurodote webhook_url kurdami užsakymą arba sukonfigūruojate numatytąjį webhook URL projekto lygmeniu.
Kai pasikeičia užsakymo būsena (pvz., iš new į completed), Cost+ siunčia POST užklausą į jūsų webhook URL.
Jūsų serveris gauna webhook, tada iškviečia Cost+ API, kad gautų pilnas užsakymo detales.
Atnaujinate savo sistemą pagal patikrintą užsakymo būseną.

Niekada nepasitikėkite vien webhook turiniu, kad įvykdytumėte užsakymą. Visada patikrinkite užsakymo būseną atlikdami GET /v1/orders/{id}/ užklausą po webhook gavimo. Webhook yra pranešimo mechanizmas, o ne tiesos šaltinis.

Webhook turinys

Webhook turinys yra JSON objektas, kuriame yra įvykio tipas ir užsakymo ID:

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

Laukas	Aprašymas
`event`	Įvykio tipas. Šiuo metu `status_changed` užsakymo atnaujinimams.
`order_id`	Unikalus užsakymo identifikatorius, kurio būsena pasikeitė.
`project_id`	Projektas, kuriam priklauso užsakymas.

Webhook URL nustatymas

Galite nustatyti webhook URL dviem būdais:

Kiekvienam užsakymui

Įtraukite webhook_url lauką kurdami užsakymą:

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

Projekto numatytasis

Sukonfigūruokite numatytąjį webhook URL savo Cost+ valdymo skydelyje projekto nustatymuose. Šis URL bus naudojamas visiems užsakymams, kurie nenurodo savo webhook_url.

Net jei turite projekto lygmens numatytąjį URL, galite jį perrašyti kiekvienam užsakymui atskirai, įtraukdami webhook_url į užsakymo kūrimo užklausą.

Pakartotinių bandymų logika

Jei jūsų serveris neatsako 2xx būsenos kodu, Cost+ bando pakartotinai pristatyti webhook:

Maksimalus bandymų skaičius: 10 bandymų
Bandymų intervalas: 2 minutės tarp kiekvieno bandymo
Pirmojo bandymo skirtasis laikas: 4 sekundės
Vėlesnių bandymų skirtasis laikas: 10 sekundžių

Jei visi 10 pakartotinių bandymų nepavyksta, webhook pažymimas kaip nepavykęs. Vis tiek galite bet kada gauti užsakymo būseną periodiškai tikrindami API.

Įsitikinkite, kad jūsų webhook galinis taškas atsako greitai (per 4 sekundes pirmajam bandymui). Bet kokį ilgai trunkantį apdorojimą atlikite asinchroniškai, prieš tai grąžinę 200 OK atsakymą.

Geriausios praktikos

Visada patikrinkite per API. Gavę webhook, iškvieskite GET /v1/orders/\{order_id\}/, kad patvirtintumėte esamą būseną prieš imdamiesi veiksmų, tokių kaip prekių siuntimas ar prieigos suteikimas.
Grąžinkite 200 greitai. Patvirtinkite webhook gavimą 200 atsakymu iš karto ir apdorokite užsakymą asinchroniškai, kad išvengtumėte skirtojo laiko.
Tvarkykite dublikatus. Jūsų webhook galinis taškas gali gauti tą patį įvykį daugiau nei kartą. Užtikrinkite, kad jūsų apdorojimo logika būtų idempotentiška.
Naudokite HTTPS. Visada naudokite HTTPS URL savo webhook galiniam taškui, kad turinys būtų perduodamas saugiai.
Registruokite webhook turinį. Saugokite gaunamus webhook duomenis derinimo ir audito tikslais.

Susiję galiniai taškai

Sukurti užsakymą — nustatyti webhook_url kiekvienam užsakymui
Atnaujinti užsakymą — atnaujinti webhook URL esamam užsakymui
Webhook įvykių schemos — turinio formatas OrderStatusChangedEvent ir TransactionStatusChangedEvent

On this page