Webhooky

Webhooky umožňují Cost+ informovat váš server v reálném čase, kdykoli se změní stav objednávky. Místo opakovaného dotazování API poskytnete URL a Cost+ na ni odešle HTTP POST požadavek při každé aktualizaci.

Jak webhooky fungují

Zadáte webhook_url při vytváření objednávky nebo nakonfigurujete výchozí webhook URL na úrovni projektu.
Když se změní stav objednávky (např. z new na completed), Cost+ odešle POST požadavek na vaši webhook URL.
Váš server přijme webhook a poté zavolá API Cost+ pro získání kompletních detailů objednávky.
Aktualizujete svůj systém na základě ověřeného stavu objednávky.

Nikdy nevěřte samotné webhookové zprávě pro vyřízení objednávky. Vždy ověřte stav objednávky požadavkem GET /v1/orders/{id}/ po přijetí webhooku. Webhook je notifikační mechanismus, nikoli zdroj pravdy.

Webhookový payload

Tělo webhooku je JSON objekt obsahující typ události a ID objednávky:

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}

Pole	Popis
`event`	Typ události. Aktuálně `status_changed` pro aktualizace objednávek.
`order_id`	Unikátní identifikátor objednávky, jejíž stav se změnil.
`project_id`	Projekt, ke kterému objednávka patří.

Nastavení webhook URL

Webhook URL můžete nastavit dvěma způsoby:

Pro jednotlivou objednávku

Zahrňte pole webhook_url při vytváření objednávky:

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

Výchozí na úrovni projektu

Nakonfigurujte výchozí webhook URL v dashboardu Cost+ v nastavení projektu. Tato URL bude použita pro všechny objednávky, které neurčí vlastní webhook_url.

I když máte výchozí URL na úrovni projektu, můžete ji přepsat u jednotlivé objednávky zahrnutím webhook_url do požadavku na vytvoření objednávky.

Logika opakování

Pokud váš server neodpoví stavovým kódem 2xx, Cost+ zopakuje doručení webhooku:

Maximální počet pokusů: 10
Interval mezi pokusy: 2 minuty
Timeout prvního pokusu: 4 sekundy
Timeout následných pokusů: 10 sekund

Pokud všech 10 pokusů selže, webhook je označen jako neúspěšný. Stav objednávky můžete kdykoli získat opakovaným dotazem na API.

Ujistěte se, že váš webhook endpoint odpovídá rychle (do 4 sekund pro první pokus). Jakékoli dlouhotrvající zpracování provádějte asynchronně po vrácení odpovědi 200 OK.

Osvědčené postupy

Vždy ověřte prostřednictvím API. Po přijetí webhooku zavolejte GET /v1/orders/\{order_id\}/ pro potvrzení aktuálního stavu, než provedete akci, jako je odeslání zboží nebo udělení přístupu.
Vraťte 200 rychle. Potvrďte webhook odpovědí 200 okamžitě a objednávku zpracujte asynchronně, abyste předešli timeoutům.
Ošetřete duplicity. Váš webhook endpoint může obdržet stejnou událost více než jednou. Ujistěte se, že vaše logika zpracování je idempotentní.
Používejte HTTPS. Vždy používejte HTTPS URL pro svůj webhook endpoint, aby byl payload přenášen bezpečně.
Logujte webhookové payloady. Ukládejte příchozí webhooková data pro účely ladění a auditu.

Související endpointy

Vytvoření objednávky — nastavení webhook_url pro jednotlivou objednávku
Aktualizace objednávky — aktualizace webhook URL na existující objednávce
Schémata webhookových událostí — formát payloadu pro OrderStatusChangedEvent a TransactionStatusChangedEvent

On this page