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.
updatedAfter nastaveným na poslední zpracovanou změnu, viz Pokyny za subúčet.Endpointy
| Endpoint | Co dělá |
|---|---|
| GET /v1/webhooks/deliveries | Přehled doručení od nejnovějšího, kurzorově. |
| POST /v1/webhooks/test | Zkuš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
pingse 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čka | Hodnota |
|---|---|
X-COINERO-EVENT-ID | Identifikátor události, shodný s eventId v těle. Podle něj deduplikujete. |
X-COINERO-TIMESTAMP | Okamžik podpisu v milisekundách od počátku unixové epochy. Každý pokus o doručení má novou hodnotu. |
X-COINERO-SIGNATURE | Podpis, 64 hexadecimálních znaků malými písmeny, viz níže. |
Content-Type | application/json; charset=utf-8 |
User-Agent | Coinero-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.
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.
Zkontrolujte čas
Zahoďte požadavek, jehož
X-COINERO-TIMESTAMPse 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ší.Spočtěte a porovnejte podpis
Porovnejte ho s
X-COINERO-SIGNATUREv konstantním čase (timingSafeEqual,hmac.compare_digest). Při neshodě odpovězte 401 a událost nezpracovávejte.Deduplikujte podle eventId
Už zpracovaný
eventIdzahoď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-TIMESTAMP | 1700000000000 |
| Tělo | {} |
| Podepisovaný text | 1700000000000{} |
| Podpis | 429ecdb3bef6f6a95706f5b09bb2e21720e7ab7a06ffeaf9e3bfa6ebe73f3e3d |
Opakování a deduplikace
| Pokus | Kdy |
|---|---|
| 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
exhausteda 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
occurredAtMsa podle stavu vdata; 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
| Typ | Kdy vzniká | Pole data |
|---|---|---|
order.pendingConfirmation | Ná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.new | Pokyn 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.partiallyFilled | Obchod 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.filled | Obchod 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.cancelled | Pokyn 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.rejected | Pokyn 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.settled | Pokyn 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.activated | Subúč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.rejected | Subúčet byl zamítnut. | Objekt subúčtu, týž jako v odpovědi GET /v1/subaccounts/{externalClientRef}, ve stavu z okamžiku události. |
subaccount.blocked | Subúčet byl zablokován. | Objekt subúčtu, týž jako v odpovědi GET /v1/subaccounts/{externalClientRef}, ve stavu z okamžiku události. |
subaccount.closed | Subúč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.ready | Denní 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.maintenance | Zač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 }. |
ping | Zkuš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
sinceastatusa stránkováním kurzorem. Položka neseeventId,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
pinga 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í 409WEBHOOK_NOT_CONFIGURED.
| Stav | Význam |
|---|---|
pending | doručení čeká na první nebo další pokus (viz nextAttemptAt) |
delivered | váš cíl odpověděl stavem 2xx |
exhausted | do 24 hodin od události neuspěl žádný pokus (u zkušební události selhal její jediný pokus) a další pokus už nebude |
skipped | událost se neodeslala, protože cíl webhooků byl zrušen |
Chyby
| Kód | Stav | Kdy |
|---|---|---|
WEBHOOK_NOT_CONFIGURED | 409 | Partnerský účet nemá cíl webhooků, zkušební událost nemá kam jít. |