POST kérés, amelyet az Aniva küld a szerverednek, amikor valami megváltozik. Nem
kell folyamatosan lekérdezned.
Az események tömörek. Az objektum azonosítóját, az új státuszt, a revíziót és a kiolvasandó url mezőt tartalmazzák. Soha
nem tartalmaznak laborértékeket vagy személyes adatokat. Az adatok lekéréséhez olvasd ki az url címet az API-kulcsoddal.
Gyors beállítás
- Készíts egy HTTPS végpontot, amely fogadja a
POSTkéréseket, és 15 másodpercen belül2xxválaszt ad. - Regisztráld a Webhook létrehozása végponttal.
Mentsd el a válaszban kapott
secretértéket. Az Aniva csak egyszer mutatja meg. - Ellenőrizd az aláírást minden kérésnél.
- Küldj egy teszteseményt. Ellenőrizd az eredményt a Kézbesítések listázása segítségével.
webhooks_manage scope-ra. Kérd meg az Anivát, hogy adja hozzá. Egy webhook ahhoz az
API-kulcshoz tartozik, amely létrehozta, és egy kulcshoz legfeljebb 5 webhook tartozhat.
Események
Csak olyan objektumokról kapsz eseményt, amelyeket az API-kulcsod a megfelelőGET végponttal olvasni tud.
A típusokat az enabled_events mezővel válaszd ki. Küldj ["*"] értéket, hogy minden típust megkapj, a később hozzáadottakat is.
- Egy státuszesemény az adott státuszba való minden belépéskor kiváltódik, visszalépéskor is. Például egy tesztkészlet, amely
dispatchedstátuszból visszakerülpendingstátuszba,home_kit_order.pendingeseményt küld. - Egyetlen változás két eseményt is küldhet azonos
status_revisionértékkel, példáulappointment.confirmedésappointment.rescheduledeseményt. - A
results.updatedaz eredmények minden változásakor kiváltódik: új érték, javítás, hiba, új vagy lecserélt dokumentum esetén, illetve ha egy minta kikerül az objektumból. Az utolsó változást követő néhány percen belül érkezik meg. - A
results.completedés aresults.faultmindig egy azonosresults_revisionértékűresults.updatedeseménnyel együtt érkezik. Az eredmények újranyílhatnak és újra lezárulhatnak, így másodikresults.completedeseményt is kaphatsz.
results.updated eseményre, ha részeredményeket szeretnél megjeleníteni, vagy a results.completed eseményre, ha csak a
végleges eredményekre szeretnél reagálni.
A results.completed az eredményértékeket követi, nem a PDF-et. A lelet PDF-je megérkezhet az értékek előtt vagy
után is. Egyes laborok először előzetes PDF-et küldenek, majd később ugyanazzal a dokumentum id értékkel lecserélik
a véglegesre. A csere results.updated eseményt küld. Olvasd ki a
documents[].original_file_name mezőt a kettő megkülönböztetéséhez: a Labor Quade esetében az előzetes lelet
(Vorbefund) _V, a végleges lelet (Endbefund) pedig _E végződésű, például
7642100312_B0012_FA_E.pdf.
A helyszín-, profil- és küldeményesemények néhány percen belül érkeznek meg. Az Aniva addig vár, amíg az objektum
2 percig nem változik, így több gyors módosítás egyetlen eseményt küld. A következő szabályok is érvényesek:
- Az anonim profilok nem küldenek eseményt.
- A küldemény nem küld eseményt, ha elveszíted hozzá a hozzáférést.
- A küldemény státuszváltozása
shipment.updatedésshipment.<status>eseményt küld azonosrevisionértékkel.
Payload
Státuszesemény adatai
appointment.confirmed
Eredményesemény adatai
home_kit_order.results.completed
Dokumentumtörlési esemény adatai
Adocument.deleted az object (document), id, previous_results_status és
results_revision mezőket tartalmazza. Nincs url mezője, mert már nincs mit olvasni.
document.deleted
Helyszín-, profil- és küldeményesemény adatai
shipment.in_transit
ping esemény data.object mezője webhook, data.id mezője pedig a webhook azonosítója.
Aláírás ellenőrzése
Az események nem tartalmaznak adatot, de így is érdemes mindegyiket ellenőrizned. Az érvényes aláírás igazolja, hogy az esemény az Anivától érkezett. Minden kérésben szerepel awebhook-id, a webhook-timestamp (Unix-
másodpercben) és a webhook-signature fejléc.
- Vedd a nyers kéréstörzset. A JSON feldolgozása előtt ellenőrizd.
- Állítsd össze az aláírt tartalmat:
{webhook-id}.{webhook-timestamp}.{raw body}. - Dekódold base64-ből a titkos kulcsod
whsec_utáni részét. Ezt használd kulcsként. - Számítsd ki az aláírt tartalom HMAC-SHA256 értékét, és kódold base64-be.
- Konstans időben hasonlítsd össze a
webhook-signaturemindenv1,<signature>bejegyzésével. A bejegyzéseket szóközök választják el. Egyetlen egyezés elég. - Utasítsd el a kérést, ha a
webhook-timestamptöbb mint 5 perccel eltér az órádtól.
Node.js
Titkos kulcs cseréje
Hívd meg a Titkos kulcs cseréje végpontot új titkos kulcs lekéréséhez. Az Aniva 24 órán át a régi és az új titkos kulccsal is aláír, ezért ezen belül állítsd élesbe az újat. Kiszivárgás után küldd el arevoke_current_secret_now: true értéket a régi titkos kulcs azonnali érvénytelenítéséhez.
Kézbesítés
- Válaszolj
2xxkóddal 15 másodpercen belül. Tárold vagy tedd sorba az eseményt, és dolgozd fel később. - Használj nyilvános hoston, a 443-as porton elérhető
httpsURL-t. Az Aniva nem követi az átirányításokat: a3xxhibának számít. - A kézbesítés legalább egyszeri és nem sorrendhelyes. Szűrd ki a duplikátumokat a
webhook-idalapján. A revíziók segítségével hagyd figyelmen kívül a régebbi eseményeket. - Válaszolj
410 Gonekóddal az események leállításához. Az Aniva azonnal letiltja a webhookot. - Az Aniva 30 napig őrzi meg a kézbesítéseket. Ezután már nem tudod őket listázni vagy újraküldeni.
Újrapróbálkozások
A nem2xx válasz, az időtúllépés vagy a hálózati hiba újrapróbálkozást indít. Minden esemény legfeljebb 10 próbálkozást kap
körülbelül három nap alatt:
A 10. próbálkozás után a kézbesítés állapota
failed lesz. Küldd el újra a
Kézbesítés újraküldése végponttal. A webhook-id változatlan marad.
Hibaértesítések
Az Aniva e-mailt küld a webhookalert_emails címeire, ha 24 órán át egyetlen kézbesítés sem sikerült, ha egy esemény
failed állapotba kerül, és ha a webhookot letiltják. Ha 5 napig nincs sikeres kézbesítés, az Aniva
letiltja a webhookot. A letiltott webhook nem kap új eseményeket, a várakozó kézbesítései pedig
törlődnek.
Az újraindításhoz javítsd ki a végpontodat, és küldd el a
status: "enabled" értéket a
Webhook frissítése végponttal. A kimaradt eseményeket az Aniva nem küldi
újra magától. Küldd el őket újra, vagy olvasd ki az aktuális állapotot a GET végpontokkal.
Ismételt lekérések
Az Aniva rövid ideig tárolja néhányGET végpont válaszát. Ha az API-kulcsod ezen az időn belül újra
elküldi ugyanazt a kérést, a tárolt választ kapod meg. Nem kapsz hibát, és a törzs formátuma is
ugyanaz.
- Egy rekord (szállítmány, otthoni tesztkészlet-rendelés, időpont, valamint az utóbbi kettő eredményei): minden híváskor az Aniva ellenőrzi, hogy a rekord változatlan-e. Ha megváltozott, friss választ kapsz.
- Egy lista legfeljebb 5 perccel lehet régebbi a benne lévő rekordoknál.
- Ugyanaz a kérés ugyanazt az API-kulcsot, ugyanazt a végpontot és ugyanazokat a lekérdezési paramétereket jelenti. Egy lista másik oldala már új kérés, és saját választ kap.
- Az Aniva csak
200választ tárol. Hibát soha nem tárol. - Az idő akkor indul, amikor az Aniva eltárolja a választ. Egy későbbi hívás nem hosszabbítja meg.
- Miután az API-kulcsod létrehoz, frissít, aktivál vagy lemond valamit, a következő lekérésed friss lesz. Ugyanennek a rekordnak a következő lekérése egy másik API-kulcsoddal is friss lesz.
- Egy tárolt szállítmányválaszban a
synced_atésupdated_atmezők régebbiek lehetnek, mint egy friss válaszban. Az állapot, a nyomon követés és a címek aktuálisak. - Egy tárolt eredményválaszban egy biomarker neve, egy mértékegység vagy egy átváltott érték legfeljebb 60 perccel lehet régebbi, miután az Aniva módosítja a katalógusát. A mért értékek aktuálisak.
- Miután az Aniva létrehoz egy webhook-eseményt a webhookodhoz, a következő lekérésed az adott rekordról, annak eredményeiről és listáiról friss lesz. Így az eseményt követő lekérés mindig mutatja a változást.
Válaszfejlécek
Ezeknek a végpontoknak minden érvényes API-kulcsra adott válasza tartalmazza az alábbi fejléceket:Bevált gyakorlatok
- Szűrd ki a duplikátumokat. Hagyd ki azokat az eseményeket, amelyek
webhook-idértékét már feldolgoztad. - Használd a revíziókat. Tárold objektumonként a legmagasabb
status_revision,results_revisionésrevisionértéket. Hagyd figyelmen kívül az ennél alacsonyabb értékű eseményeket. - Kérd le az
urlcímet. Az esemény azt jelzi, hogy valami megváltozott. AGETvégpont mondja meg, mi. - Válaszolj gyorsan. Tedd sorba az eseményt, és válaszolj
2xxkóddal, mielőtt feldolgozod. - Egyeztess rendszeresen. Futtass rendszeres feladatot, amely a
GETvégpontokkal kiolvassa a nyitott objektumokat. A polling továbbra is érvényes tartalék megoldás. Az ismételt lekérés tárolt választ is adhat, lásd: Ismételt lekérések. - Tesztelj minden élesítés után. Használd a Tesztesemény küldése végpontot.