Cost+Docs

Webhook-i

Prejemajte obvestila o statusu plačil v realnem času

Webhook-i omogočajo Cost+, da obvesti vaš strežnik v realnem času, kadar koli se status naročila spremeni. Namesto rednega poizvedovanja API-ja navedete URL in Cost+ pošlje zahtevo HTTP POST nanj ob vsaki posodobitvi.

Kako webhook-i delujejo

  1. Navedete webhook_url ob ustvarjanju naročila ali konfigurirate privzeti webhook URL na ravni projekta.
  2. Ko se status naročila spremeni (npr. iz new v completed), Cost+ pošlje zahtevo POST na vaš webhook URL.
  3. Vaš strežnik prejme webhook, nato pokliče Cost+ API za pridobitev celotnih podrobnosti naročila.
  4. Posodobite svoj sistem glede na preverjeni status naročila.

Nikoli ne zaupajte samo koristnim podatkom webhook-a za izpolnitev naročila. Vedno preverite status naročila z zahtevo GET /v1/orders/{id}/ po prejemu webhook-a. Webhook je mehanizem obveščanja, ne vir resnice.

Koristni podatki webhook-a

Telo webhook-a je JSON objekt, ki vsebuje tip dogodka in ID naročila:

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}
PoljeOpis
eventTip dogodka. Trenutno status_changed za posodobitve naročil.
order_idEdinstveni identifikator naročila, katerega status se je spremenil.
project_idProjekt, ki mu naročilo pripada.

Nastavitev webhook URL-ja

Webhook URL lahko nastavite na dva načina:

Za posamezno naročilo

Vključite polje webhook_url ob ustvarjanju naročila:

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

Privzeta nastavitev projekta

Konfigurirajte privzeti webhook URL v vaši nadzorni plošči Cost+ pod nastavitvami projekta. Ta URL bo uporabljen za vsa naročila, ki ne navedejo lastnega webhook_url.

Tudi če imate privzeto nastavitev na ravni projekta, jo lahko preglasite za posamezno naročilo z vključitvijo webhook_url v zahtevo za ustvarjanje naročila.

Logika ponovnih poskusov

Če vaš strežnik ne odgovori s statusno kodo 2xx, Cost+ ponovi dostavo webhook-a:

  • Največje število ponovitev: 10 poskusov
  • Interval ponovitev: 2 minuti med vsakim poskusom
  • Časovna omejitev prvega poskusa: 4 sekunde
  • Časovna omejitev nadaljnjih poskusov: 10 sekund

Če vseh 10 poskusov ponovitev spodleti, je webhook označen kot neuspešen. Status naročila lahko kadarkoli pridobite z rednim poizvedovanjem API-ja.

Poskrbite, da vaš webhook naslov odgovori hitro (v 4 sekundah za prvi poskus). Izvedite morebitno dolgotrajno obdelavo asinhrono po vrnitvi odgovora 200 OK.

Najboljše prakse

  • Vedno preverite prek API-ja. Po prejemu webhook-a pokličite GET /v1/orders/\{order_id\}/ za potrditev trenutnega statusa, preden ukrepate, kot je pošiljanje blaga ali odobritev dostopa.
  • Hitro vrnite 200. Potrdite webhook z odgovorom 200 takoj in obdelajte naročilo asinhrono, da se izognete časovnim omejitvam.
  • Obdelajte podvojitve. Vaš webhook naslov lahko prejme isti dogodek večkrat. Zagotovite, da je vaša logika obdelave idempotentna.
  • Uporabite HTTPS. Vedno uporabite HTTPS URL za vaš webhook naslov, da zagotovite varno prenašanje koristnih podatkov.
  • Beležite koristne podatke webhook-ov. Shranjujte prihajajoče podatke webhook-ov za odpravljanje napak in revizijske namene.

Povezane končne točke

On this page