Přejít na hlavní obsah
Webhook je HTTPS požadavek POST, který Aniva pošle na tvůj server, když se něco změní. Nemusíš se pravidelně dotazovat. Události jsou úsporné. Obsahují ID objektu, nový stav, revizi a url pro načtení. Nikdy neobsahují laboratorní hodnoty ani osobní údaje. Data získáš načtením url pomocí svého API klíče.

Rychlé nastavení

  1. Vytvoř HTTPS endpoint, který přijímá POST a odpoví 2xx do 15 sekund.
  2. Zaregistruj ho pomocí Vytvořit webhook. Ulož si secret z odpovědi. Aniva ho zobrazí jen jednou.
  3. Ověř podpis každého požadavku.
  4. Pošli testovací událost. Výsledek zkontroluj v Seznamu doručení.
Tvůj API klíč potřebuje scope webhooks_manage. Požádej Aniva o jeho přidání. Webhook patří API klíči, který ho vytvořil, a jeden klíč může vlastnit nejvýše 5 webhooků.

Události

Událost dostaneš jen pro objekty, které tvůj API klíč může číst přes odpovídající GET endpoint. Typy vyber pomocí enabled_events. Pošli ["*"], pokud chceš dostávat všechny typy, i ty přidané později.
  • Stavová událost se spustí při každém přechodu do daného stavu, i při přechodu zpět. Například sada, která přejde z dispatched zpět do pending, pošle home_kit_order.pending.
  • Jedna změna může poslat dvě události se stejným status_revision, například appointment.confirmed a appointment.rescheduled.
  • results.updated se spustí při každé změně výsledků: nová hodnota, oprava, chyba, nový nebo nahrazený dokument nebo vzorek, který objekt opustí. Dorazí během několika minut od poslední změny.
  • results.completed a results.fault vždy přijdou společně s results.updated se stejným results_revision. Výsledky se mohou znovu otevřít a znovu dokončit, takže můžeš dostat druhé results.completed.
Přihlas se k odběru results.updated pro zobrazení částečných výsledků, nebo k results.completed, pokud chceš reagovat jen na finální výsledky. results.completed se řídí hodnotami výsledků, ne PDF. PDF se zprávou může dorazit před hodnotami i po nich. Některé laboratoře nejdřív pošlou předběžné PDF a později ho pod stejným id dokumentu nahradí finálním. Nahrazení pošle results.updated. Podle documents[].original_file_name je rozlišíš: u Labor Quade končí předběžná zpráva (Vorbefund) na _V a finální zpráva (Endbefund) na _E, například 7642100312_B0012_FA_E.pdf. Události lokalit, profilů a zásilek dorazí během několika minut. Aniva čeká, až se objekt 2 minuty nezmění, takže série úprav pošle jednu událost. Platí také tato pravidla:
  • Anonymní profily neposílají žádné události.
  • Zásilka nepošle žádnou událost, když k ní ztratíš přístup.
  • Změna stavu zásilky pošle shipment.updated a událost shipment.<status> se stejným revision.

Payload

Data stavové události

appointment.confirmed

Data události výsledků

home_kit_order.results.completed

Data události smazání dokumentu

document.deleted obsahuje object (document), id, previous_results_status a results_revision. Nemá žádné url, protože už není co číst.
document.deleted

Data událostí lokalit, profilů a zásilek

shipment.in_transit
Událost ping obsahuje data.object webhook a data.id, tedy ID webhooku.

Ověření podpisu

Události neobsahují žádná data, přesto je dobré každou z nich ověřit. Platný podpis dokazuje, že událost poslala Aniva. Každý požadavek obsahuje hlavičky webhook-id, webhook-timestamp (Unix sekundy) a webhook-signature.
  1. Vezmi nezpracované tělo požadavku. Ověř ho ještě před parsováním JSON.
  2. Sestav podepsaný obsah {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Dekóduj z base64 část svého tajného klíče za whsec_. Použij ji jako klíč.
  4. Spočítej HMAC-SHA256 podepsaného obsahu a zakóduj ho do base64.
  5. Porovnej ho v konstantním čase s každou položkou v1,<signature> v webhook-signature. Položky jsou oddělené mezerami. Stačí jedna shoda.
  6. Odmítni požadavek, pokud se webhook-timestamp liší od tvých hodin o více než 5 minut.
Node.js
Jde o schéma Standard Webhooks. Knihovny Standard Webhooks existují pro většinu jazyků a zvládnou to jedním voláním.

Rotace tajného klíče

Voláním Rotovat tajný klíč získáš nový tajný klíč. Po dobu 24 hodin Aniva podepisuje starým i novým tajným klíčem, takže nový nasaď během této doby. Po úniku pošli revoke_current_secret_now: true a starý tajný klíč hned přestane platit.

Doručování

  • Odpověz 2xx do 15 sekund. Událost ulož nebo zařaď do fronty a zpracuj ji později.
  • Použij https URL na portu 443 s veřejným hostitelem. Aniva nesleduje přesměrování: 3xx se počítá jako selhání.
  • Doručování probíhá alespoň jednou a bez zaručeného pořadí. Duplicity zahazuj podle webhook-id. Pomocí revizí ignoruj starší událost.
  • Pro zastavení událostí odpověz 410 Gone. Aniva webhook hned vypne.
  • Aniva uchovává doručení 30 dní. Poté je už nemůžeš vypsat ani znovu odeslat.

Opakované pokusy

Odpověď jiná než 2xx, vypršení času nebo chyba sítě spustí opakovaný pokus. Každá událost má až 10 pokusů během zhruba tří dnů: Po 10. pokusu má doručení stav failed. Pošli ho znovu pomocí Znovu odeslat doručení. Ponechá si stejné webhook-id.

Upozornění na selhání

Aniva pošle e-mail na adresy v alert_emails webhooku, když se za 24 hodin žádné doručení nepodaří, když je událost ve stavu failed a když se webhook vypne. Po 5 dnech bez úspěšného doručení Aniva webhook vypne. Vypnutý webhook nedostává žádné nové události a jeho čekající doručení se zruší. Pokud chceš začít znovu, oprav svůj endpoint a pošli status: "enabled" pomocí Aktualizovat webhook. Zmeškané události se samy znovu nepošlou. Pošli je znovu, nebo si aktuální stav načti přes GET endpointy.

Opakovaná čtení

Aniva na krátkou dobu ukládá odpověď některých GET endpointů. Když tvůj API klíč během této doby pošle stejný požadavek znovu, dostaneš uloženou odpověď. Nedostaneš žádnou chybu a tělo má stejný formát.
  • Jeden záznam (zásilka, objednávka domácí testovací sady, termín a výsledky posledních dvou): při každém volání Aniva zkontroluje, jestli se záznam nezměnil. Pokud se změnil, dostaneš čerstvou odpověď.
  • Seznam může být starší než jeho záznamy, nejvýše o 5 minut.
Pokud se chceš o změně dozvědět hned, použij události webhooku z tabulky.
  • Stejný požadavek znamená stejný API klíč, stejný endpoint a stejné parametry dotazu. Jiná stránka seznamu je jiný požadavek a dostane vlastní odpověď.
  • Aniva ukládá jen odpověď 200. Chyba se neukládá nikdy.
  • Čas začíná běžet ve chvíli, kdy Aniva odpověď uloží. Pozdější volání ho neprodlužuje.
  • Poté, co tvůj API klíč něco vytvoří, aktualizuje, aktivuje nebo zruší, bude tvé další čtení čerstvé. Čerstvé bude i další čtení tohoto záznamu s jiným tvým API klíčem.
  • V uložené odpovědi zásilky mohou být pole synced_at a updated_at starší než v čerstvé odpovědi. Stav, sledování a adresy jsou aktuální.
  • V uložené odpovědi s výsledky může být název biomarkeru, jednotka nebo přepočítaná hodnota až 60 minut stará poté, co Aniva změní svůj katalog. Naměřené hodnoty jsou aktuální.
  • Poté, co Aniva vytvoří událost pro tvůj webhook, bude tvé další čtení daného záznamu, jeho výsledků i jeho seznamů čerstvé. Čtení po události tak vždy ukáže změnu.

Hlavičky odpovědi

Každá odpověď těchto endpointů pro platný API klíč obsahuje tyto hlavičky:

Osvědčené postupy

  • Zahazuj duplicity. Přeskoč událost s webhook-id, které už máš zpracované.
  • Používej revize. Ukládej nejvyšší status_revision, results_revision a revision pro každý objekt. Událost s nižší hodnotou ignoruj.
  • Načítej url. Událost říká, že se něco změnilo. GET endpoint říká co.
  • Odpovídej rychle. Zařaď událost do fronty a odpověz 2xx dřív, než ji zpracuješ.
  • Synchronizuj stav. Spouštěj pravidelnou úlohu, která čte otevřené objekty přes GET endpointy. Pravidelné dotazování zůstává platnou záložní možností. Opakované čtení může vrátit uloženou odpověď, viz Opakovaná čtení.
  • Testuj po každém nasazení. Použij Odeslat testovací událost.