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
- Navedete
webhook_urlob ustvarjanju naročila ali konfigurirate privzeti webhook URL na ravni projekta. - Ko se status naročila spremeni (npr. iz
newvcompleted), Cost+ pošlje zahtevo POST na vaš webhook URL. - Vaš strežnik prejme webhook, nato pokliče Cost+ API za pridobitev celotnih podrobnosti naročila.
- 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"
}| Polje | Opis |
|---|---|
event | Tip dogodka. Trenutno status_changed za posodobitve naročil. |
order_id | Edinstveni identifikator naročila, katerega status se je spremenil. |
project_id | Projekt, 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
200takoj 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
- Ustvari naročilo — nastavite
webhook_urlza posamezno naročilo - Posodobi naročilo — posodobite webhook URL na obstoječem naročilu
- Sheme webhook dogodkov — oblika koristnih podatkov za
OrderStatusChangedEventinTransactionStatusChangedEvent