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
- Zadate
webhook_urlpri vytvarani objednavky alebo nastavite predvolenu webhook URL na urovni projektu. - Ked sa zmeni stav objednavky (napr. z
newnacompleted), Cost+ posle POST poziadavku na vasu webhook URL. - Vas server prijme webhook, potom zavola Cost+ API na ziskanie uplnych podrobnosti objednavky.
- 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"
}| Pole | Popis |
|---|---|
event | Typ udalosti. Momentalne status_changed pre aktualizacie objednavok. |
order_id | Jediny identifikator objednavky, ktorej stav sa zmenil. |
project_id | Projekt, 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
200okamzite 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
- Vytvorenie objednavky -- nastavenie
webhook_urlpre kazdu objednavku - Aktualizacia objednavky -- aktualizacia webhook URL na existujucej objednavke
- Schemy udalosti webhookov -- format payloadu pre
OrderStatusChangedEventaTransactionStatusChangedEvent