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í
- Vytvoř HTTPS endpoint, který přijímá
POSTa odpoví2xxdo 15 sekund. - Zaregistruj ho pomocí Vytvořit webhook.
Ulož si
secretz odpovědi. Aniva ho zobrazí jen jednou. - Ověř podpis každého požadavku.
- Pošli testovací událost. Výsledek zkontroluj v Seznamu doručení.
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
dispatchedzpět dopending, pošlehome_kit_order.pending. - Jedna změna může poslat dvě události se stejným
status_revision, napříkladappointment.confirmedaappointment.rescheduled. results.updatedse 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.completedaresults.faultvždy přijdou společně sresults.updatedse stejnýmresults_revision. Výsledky se mohou znovu otevřít a znovu dokončit, takže můžeš dostat druhéresults.completed.
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.updateda událostshipment.<status>se stejnýmrevision.
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
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čkywebhook-id, webhook-timestamp (Unix sekundy) a webhook-signature.
- Vezmi nezpracované tělo požadavku. Ověř ho ještě před parsováním JSON.
- Sestav podepsaný obsah
{webhook-id}.{webhook-timestamp}.{raw body}. - Dekóduj z base64 část svého tajného klíče za
whsec_. Použij ji jako klíč. - Spočítej HMAC-SHA256 podepsaného obsahu a zakóduj ho do base64.
- Porovnej ho v konstantním čase s každou položkou
v1,<signature>vwebhook-signature. Položky jsou oddělené mezerami. Stačí jedna shoda. - Odmítni požadavek, pokud se
webhook-timestampliší od tvých hodin o více než 5 minut.
Node.js
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šlirevoke_current_secret_now: true a starý tajný klíč hned přestane platit.
Doručování
- Odpověz
2xxdo 15 sekund. Událost ulož nebo zařaď do fronty a zpracuj ji později. - Použij
httpsURL na portu 443 s veřejným hostitelem. Aniva nesleduje přesměrování:3xxse 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 valert_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ýchGET 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.
- 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_ataupdated_atstarší 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_revisionarevisionpro každý objekt. Událost s nižší hodnotou ignoruj. - Načítej
url. Událost říká, že se něco změnilo.GETendpoint říká co. - Odpovídej rychle. Zařaď událost do fronty a odpověz
2xxdřív, než ji zpracuješ. - Synchronizuj stav. Spouštěj pravidelnou úlohu, která čte otevřené objekty přes
GETendpointy. 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.