Cost+Docs

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

  1. Navedete webhook_url prilikom stvaranja narudžbe ili konfigurirate zadani webhook URL na razini projekta.
  2. Kada se status narudžbe promijeni (npr. iz new u completed), Cost+ šalje POST zahtjev na vaš webhook URL.
  3. Vaš poslužitelj prima webhook, zatim poziva Cost+ API za dohvaćanje potpunih detalja narudžbe.
  4. 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"
}
PoljeOpis
eventTip događaja. Trenutno status_changed za ažuriranja narudžbi.
order_idJedinstveni identifikator narudžbe čiji se status promijenio.
project_idProjekt 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 200 odgovorom 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

On this page