Získat API klíč
Subúčty (partneři)

Webhooky

Coinero pošle změny pokynů a subúčtů na váš HTTPS cíl, podepsané tajemstvím, které znáte jen vy a Coinero.

Webhooky doplňují dotazování, nenahrazují ho.

Událost se doručí alespoň jednou a pořadí událostí není zaručené. Po výpadku svého cíle dohoňte stav dotazem GET /v1/subaccounts/orders s updatedAfter nastaveným na poslední zpracovanou změnu, viz Pokyny za subúčet.

Endpointy

EndpointCo dělá
GET /v1/webhooks/deliveriesPřehled doručení od nejnovějšího, kurzorově.
POST /v1/webhooks/testZkušební událost ping a výsledek jediného pokusu.

Vyžadují partnerský klíč s oprávněním subaccounts a podpis. Cíl webhooků API nemění.

Nastavení cíle

Cíl webhooků nastaví Coinero podle vašeho zadání; API ho nemění. Zadává se:

  • adresa cíle: jen https, veřejná adresa (kontroluje se i podle DNS v okamžiku spojení), bez přesměrování; přesměrování se nesleduje a bere se jako neúspěšný pokus;
  • tajemství webhooku: Base64, 44 znaků, zobrazí se jednou; rotuje se nezávisle na API klíči;
  • výběr událostí, které se mají posílat (zkušební událost ping se posílá vždy);
  • pozastavení: pozastavený cíl se neobsluhuje, doručení se ale dál zakládají a po obnovení se doženou, pokud mezitím neuplynula lhůta 24 hodin; co vypršelo, skončí jako exhausted.

Požadavek na váš cíl

HlavičkaHodnota
X-COINERO-EVENT-IDIdentifikátor události, shodný s eventId v těle. Podle něj deduplikujete.
X-COINERO-TIMESTAMPOkamžik podpisu v milisekundách od počátku unixové epochy. Každý pokus o doručení má novou hodnotu.
X-COINERO-SIGNATUREPodpis, 64 hexadecimálních znaků malými písmeny, viz níže.
Content-Typeapplication/json; charset=utf-8
User-AgentCoinero-Webhooks/1

Tělo je JSON { eventId, type, occurredAt, occurredAtMs, partnerCode, data }. Pole data je týž objekt jako v odpovědi REST (pokyn s blokem partner, nebo subúčet), serializovaný stejně, ve stavu z okamžiku události; u události report.daily.ready nese souhrn hotového denního reportu. Tělo se uloží při vzniku události a každé opakování posílá totéž. Časy jsou dvakrát: ISO 8601 v UTC a milisekundy.

Odpovězte stavem 2xx do 10 sekund. Cokoli jiného, včetně přesměrování a překročení času, je neúspěšný pokus. Zpracování, které trvá déle, odložte a odpovězte hned.

Ověření podpisu

Podpis je HMAC-SHA256 nad timestamp + tělo, kde timestamp je hodnota hlavičky X-COINERO-TIMESTAMP a tělo jsou přesné bajty požadavku. Klíčem jsou bajty tajemství dekódované z Base64, výsledek je hex malými písmeny. Je to tentýž výpočet jako u podpisu požadavků s prázdnou metodou a cestou, takže ho umí i vaše knihovna pro podpis.

  1. Přečtěte tělo jako bajty

    Nepřeformátovávejte ho a neparsujte před ověřením: podpis kryje přesné bajty.

  2. Zkontrolujte čas

    Zahoďte požadavek, jehož X-COINERO-TIMESTAMP se od vašich hodin liší o víc než pár minut (ukázka používá 5 minut). Chrání před přehráním zachyceného požadavku. Každý pokus má čerstvý čas, takže opakování tolerance neporuší.

  3. Spočtěte a porovnejte podpis

    Porovnejte ho s X-COINERO-SIGNATURE v konstantním čase (timingSafeEqual, hmac.compare_digest). Při neshodě odpovězte 401 a událost nezpracovávejte.

  4. Deduplikujte podle eventId

    Už zpracovaný eventId zahoďte, ale odpovězte 2xx, jinak ho Coinero pošle znovu.

Referenční vektor pro kontrolu vlastní implementace (stejný používají ukázky vpravo):

Tajemství (Base64, 32 nulových bajtů)AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
X-COINERO-TIMESTAMP1700000000000
Tělo{}
Podepisovaný text1700000000000{}
Podpis429ecdb3bef6f6a95706f5b09bb2e21720e7ab7a06ffeaf9e3bfa6ebe73f3e3d

Opakování a deduplikace

PokusKdy
1. opakování1 minuta po neúspěšném pokusu
2. opakování5 minut po předchozím pokusu
3. opakování15 minut po předchozím pokusu
4. opakování60 minut po předchozím pokusu
další opakováníkaždé 2 hodiny, dokud neuplyne 24 hodin od vzniku události
  • Pokus, který by připadl na uplynutí 24 hodin od vzniku události nebo později, se neplánuje. Doručení bez úspěchu skončí ve stavu exhausted a už se neopakuje.
  • Doručení alespoň jednou (at least once): událost může přijít víckrát (opakování, ztracená odpověď). Deduplikujte podle eventId.
  • Pořadí není zaručené. Události téhož pokynu mohou dorazit v jiném pořadí. Řaďte podle occurredAtMs a podle stavu v data; novější stav nepřepisujte starším.
  • Tělo události se nemění ani tehdy, když předmět události mezitím postoupil dál. Vzniklo-li víc přechodů v jednom uložení, mají jejich události snímek koncového stavu toho uložení.

Události

TypKdy vznikáPole data
order.pendingConfirmationNákup přijatý přes API čeká na potvrzení blokace peněz klienta.Objekt pokynu s blokem partner, týž jako v odpovědi GET …/orders/{orderId}, ve stavu z okamžiku události.
order.newPokyn je financovaný (nákup po potvrzení) nebo přijatý k provedení (prodej). Vzniká i u pokynů zadaných za subúčet mimo API.Objekt pokynu s blokem partner, týž jako v odpovědi GET …/orders/{orderId}, ve stavu z okamžiku události.
order.partiallyFilledObchod skončil částečným plněním a zbytek se vrátil. Není to průběžné plnění: událost přijde jednou, na konci obchodu.Objekt pokynu s blokem partner, týž jako v odpovědi GET …/orders/{orderId}, ve stavu z okamžiku události.
order.filledObchod skončil plným naplněním.Objekt pokynu s blokem partner, týž jako v odpovědi GET …/orders/{orderId}, ve stavu z okamžiku události.
order.cancelledPokyn byl zrušen: nepotvrzený nákup po lhůtě blokace (rejectionReason blockTimeout), nebo zrušení bez plnění.Objekt pokynu s blokem partner, týž jako v odpovědi GET …/orders/{orderId}, ve stavu z okamžiku události.
order.rejectedPokyn byl zamítnut kvůli pohybu ceny přes ochrannou mez (priceMoved), odmítnutí burzou nebo obchodním pravidlům.Objekt pokynu s blokem partner, týž jako v odpovědi GET …/orders/{orderId}, ve stavu z okamžiku události.
order.settledPokyn je vypořádaný s vaším partnerským účtem, pole partner.settledAt je vyplněné. Stav status se nemění.Objekt pokynu s blokem partner, týž jako v odpovědi GET …/orders/{orderId}, ve stavu z okamžiku události.
subaccount.activatedSubúčet je aktivní, po automatické aktivaci s převzatou identifikací i po aktivaci Coinerem.Objekt subúčtu, týž jako v odpovědi GET /v1/subaccounts/{externalClientRef}, ve stavu z okamžiku události.
subaccount.rejectedSubúčet byl zamítnut.Objekt subúčtu, týž jako v odpovědi GET /v1/subaccounts/{externalClientRef}, ve stavu z okamžiku události.
subaccount.blockedSubúčet byl zablokován.Objekt subúčtu, týž jako v odpovědi GET /v1/subaccounts/{externalClientRef}, ve stavu z okamžiku události.
subaccount.closedSubúčet byl ukončen (vaším požadavkem DELETE /v1/subaccounts/{externalClientRef}, nebo Coinerem). Stav closed je konečný; opakované ukončení událost nepošle.Objekt subúčtu, týž jako v odpovědi GET /v1/subaccounts/{externalClientRef}, ve stavu z okamžiku události.
report.daily.readyDenní report za předchozí pražský den je po uzávěrce hotový a už se nemění. Přijde pár minut po uzávěrce dne (ve výchozím nastavení ve 3:00 pražského času) za každý den, i za den bez pokynů a plateb, abyste věděli, že má kontrola proběhnout.Objekt { date, closesAt, closesAtMs, ordersCount, paymentsCount, hasStatement }: date je den reportu (YYYY-MM-DD, hodnota parametru date pro GET /v1/reports/daily), closesAt jeho uzávěrka, ordersCount a paymentsCount počet položek v polích orders a payments reportu a hasStatement, zda report nese denní výpis.
service.maintenanceZačala údržba API, nebo se ohlásilo, změnilo či zrušilo plánované okno údržby, které ještě neskončilo.Objekt { active, plannedFrom, plannedFromMs, plannedUntil, plannedUntilMs, message }: active říká, zda odstávka právě probíhá, meze okna jsou null, když nejsou známé, message je tentýž text jako maintenance.description ve stavu služby.
service.resumedÚdržba skončila a API znovu přijímá požadavky.Objekt { resumedAt, resumedAtMs }.
pingZkušební událost z POST /v1/webhooks/test. Posílá se vždy, výběr událostí ji neomezuje.Prázdný objekt.

Ukázky těl všech událostí jsou v kapitole Události webhooků. Ve verzi v1 mohou přibýt nové typy událostí; neznámý typ zpracujte bez selhání a odpovězte 2xx.

Přehled doručení a zkušební událost

  • GET /v1/webhooks/deliveries vrací doručení od nejnovějšího s filtry since a status a stránkováním kurzorem. Položka nese eventId, type, počet pokusů, stav, stav HTTP poslední odpovědi a termín dalšího pokusu; těla událostí ne. Přehled se uchovává 90 dní.
  • POST /v1/webhooks/test pošle událost ping a vrátí výsledek jediného pokusu. Neopakuje se a posílá se i na pozastavený cíl. Povolených je 5 za minutu na klíč. Bez nastaveného cíle vrací 409 WEBHOOK_NOT_CONFIGURED.
StavVýznam
pendingdoručení čeká na první nebo další pokus (viz nextAttemptAt)
deliveredváš cíl odpověděl stavem 2xx
exhausteddo 24 hodin od události neuspěl žádný pokus (u zkušební události selhal její jediný pokus) a další pokus už nebude
skippedudálost se neodeslala, protože cíl webhooků byl zrušen

Chyby

KódStavKdy
WEBHOOK_NOT_CONFIGURED409Partnerský účet nemá cíl webhooků, zkušební událost nemá kam jít.