Cost+Docs

Webhooky

Prijimajte notifikacie o stave platieb v realnom case

Webhooky umoznuju Cost+ notifikovat vas server v realnom case vzdy, ked sa zmeni stav objednavky. Namiesto dotazovania API uvediete URL adresu a Cost+ posle HTTP POST poziadavku vzdy, ked nastane aktualizacia.

Ako webhooky funguju

  1. Zadate webhook_url pri vytvarani objednavky alebo nastavite predvolenu webhook URL na urovni projektu.
  2. Ked sa zmeni stav objednavky (napr. z new na completed), Cost+ posle POST poziadavku na vasu webhook URL.
  3. Vas server prijme webhook, potom zavola Cost+ API na ziskanie uplnych podrobnosti objednavky.
  4. Aktualizujete svoj system na zaklade overeneho stavu objednavky.

Nikdy neverite len payloadu webhooku pri vybavovani objednavky. Vzdy overte stav objednavky volanim GET /v1/orders/{id}/ po prijati webhooku. Webhook je mechanizmus notifikacie, nie zdroj pravdy.

Payload webhooku

Telo webhooku je JSON objekt obsahujuci typ udalosti a ID objednavky:

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}
PolePopis
eventTyp udalosti. Momentalne status_changed pre aktualizacie objednavok.
order_idJediny identifikator objednavky, ktorej stav sa zmenil.
project_idProjekt, ktoremu objednavka patri.

Nastavenie webhook URL

Webhook URL mozete nastavit dvoma sposobmi:

Pre kazdu objednavku

Zahrnte pole webhook_url pri vytvarani objednavky:

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

Predvolene pre projekt

Nakonfigurujte predvolenu webhook URL na dashboarde Cost+ v nastaveniach projektu. Tato URL sa pouzije pre vsetky objednavky, ktore nezdaju vlastnu webhook_url.

Aj ked mate predvolenu URL na urovni projektu, mozete ju pre kazdu objednavku prepísat zahrnutim webhook_url v poziadavke na vytvorenie objednavky.

Logika opakovanych pokusov

Ak vas server neodpovie stavovym kodom 2xx, Cost+ zopakuje dorucenie webhooku:

  • Maximalny pocet pokusov: 10
  • Interval medzi pokusmi: 2 minuty
  • Casovy limit prveho pokusu: 4 sekundy
  • Casovy limit naslednych pokusov: 10 sekund

Ak vsetkych 10 pokusov zlyha, webhook sa oznaci ako neuspesny. Stav objednavky mozete kedykolvek ziskat dotazovanim API.

Uistite sa, ze vas webhook endpoint reaguje rychlo (do 4 sekund pri prvom pokuse). Akekolvek dlhotrvajuce spracovanie vykonajte asynchronne po vrateni odpovede 200 OK.

Osvedcene postupy

  • Vzdy overujte cez API. Po prijati webhooku zavolajte GET /v1/orders/\{order_id\}/ na potvrdenie aktualneho stavu pred vykonanim akcie, ako je odoslanie tovaru alebo udelenie pristupu.
  • Vracajte 200 rychlo. Potvrdte webhook odpovedu 200 okamzite a spracujte objednavku asynchronne, aby ste predisli prekroceniu casoveho limitu.
  • Spracujte duplikaty. Vas webhook endpoint moze prijat tu istu udalost viackrat. Zaistite, aby vasa spracujuca logika bola idempotentna.
  • Pouzivajte HTTPS. Vzdy pouzivajte HTTPS URL pre vas webhook endpoint, aby sa payload prenasal bezpecne.
  • Zaznamenavajte payloady webhookov. Ukladajte prichadzajuce udaje webhookov na ucely ladenia a auditu.

Suvisiace endpointy

On this page