Webhookovi
Primajte obavijesti o statusu plaćanja u stvarnom vremenu
Webhookovi omogućuju Cost+ da obavijesti vaš poslužitelj u stvarnom vremenu kad god se promijeni status narudžbe. Umjesto anketiranja API-ja, navedete URL i Cost+ šalje HTTP POST zahtjev na njega kad god postoji ažuriranje.
Kako webhookovi funkcioniraju
- Navedete
webhook_urlprilikom stvaranja narudžbe ili konfigurirate zadani webhook URL na razini projekta. - Kada se status narudžbe promijeni (npr. iz
newucompleted), Cost+ šalje POST zahtjev na vaš webhook URL. - Vaš poslužitelj prima webhook, zatim poziva Cost+ API za dohvaćanje potpunih detalja narudžbe.
- Ažurirate svoj sustav na temelju provjerenog statusa narudžbe.
Nikada ne vjerujte samo webhook podacima za ispunjenje narudžbe. Uvijek provjerite status narudžbe upućivanjem GET /v1/orders/{id}/ zahtjeva nakon primitka webhooka. Webhook je mehanizam obavještavanja, a ne izvor istine.
Webhook podaci
Tijelo webhooka je JSON objekt koji sadrži tip događaja i ID narudžbe:
{
"event": "status_changed",
"order_id": "b9ae6...",
"project_id": "proj_abc123"
}| Polje | Opis |
|---|---|
event | Tip događaja. Trenutno status_changed za ažuriranja narudžbi. |
order_id | Jedinstveni identifikator narudžbe čiji se status promijenio. |
project_id | Projekt kojem narudžba pripada. |
Postavljanje webhook URL-a
Webhook URL možete postaviti na dva načina:
Po narudžbi
Uključite polje webhook_url prilikom stvaranja narudžbe:
{
"currency": "EUR",
"amount": 1295,
"webhook_url": "https://www.example.com/webhook"
}Zadana postavka projekta
Konfigurirajte zadani webhook URL u vašoj Cost+ nadzornoj ploči pod postavkama projekta. Ovaj URL koristit će se za sve narudžbe koje ne navode vlastiti webhook_url.
Čak i ako imate zadanu postavku na razini projekta, možete je nadjačati za pojedinačnu narudžbu uključivanjem webhook_url u zahtjev za stvaranje narudžbe.
Logika ponovnih pokušaja
Ako vaš poslužitelj ne odgovori s 2xx statusnim kodom, Cost+ ponavlja isporuku webhooka:
- Maksimalan broj ponovnih pokušaja: 10 pokušaja
- Interval između pokušaja: 2 minute između svakog pokušaja
- Istek prvog pokušaja: 4 sekunde
- Istek naknadnih pokušaja: 10 sekundi
Ako svih 10 ponovnih pokušaja ne uspije, webhook se označava kao neuspjeo. I dalje možete dohvatiti status narudžbe u bilo kojem trenutku anketiranjem API-ja.
Pobrinite se da vaša webhook krajnja točka odgovara brzo (unutar 4 sekunde za prvi pokušaj). Obavljajte svaku dugotrajnu obradu asinkrono nakon vraćanja 200 OK odgovora.
Najbolje prakse
- Uvijek provjerite putem API-ja. Nakon primitka webhooka pozovite
GET /v1/orders/\{order_id\}/kako biste potvrdili trenutni status prije poduzimanja radnji poput slanja robe ili odobravanja pristupa. - Brzo vratite 200. Potvrdite webhook s
200odgovorom odmah i obradite narudžbu asinkrono kako biste izbjegli isteke. - Rukujte duplikatima. Vaša webhook krajnja točka može primiti isti događaj više puta. Pobrinite se da je vaša logika obrade idempotentna.
- Koristite HTTPS. Uvijek koristite HTTPS URL za svoju webhook krajnju točku kako biste osigurali siguran prijenos podataka.
- Zapisujte webhook podatke. Pohranite dolazne webhook podatke za potrebe otklanjanja problema i revizije.
Povezane krajnje točke
- Stvori narudžbu — postavite
webhook_urlpo narudžbi - Ažuriraj narudžbu — ažurirajte webhook URL na postojećoj narudžbi
- Sheme webhook događaja — format podataka za
OrderStatusChangedEventiTransactionStatusChangedEvent