Ugrás a fő tartalomhoz
A webhook egy HTTPS 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

  1. Készíts egy HTTPS végpontot, amely fogadja a POST kéréseket, és 15 másodpercen belül 2xx választ ad.
  2. Regisztráld a Webhook létrehozása végponttal. Mentsd el a válaszban kapott secret értéket. Az Aniva csak egyszer mutatja meg.
  3. Ellenőrizd az aláírást minden kérésnél.
  4. Küldj egy teszteseményt. Ellenőrizd az eredményt a Kézbesítések listázása segítségével.
Az API-kulcsodnak szüksége van a 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 dispatched státuszból visszakerül pending státuszba, home_kit_order.pending eseményt küld.
  • Egyetlen változás két eseményt is küldhet azonos status_revision értékkel, például appointment.confirmed és appointment.rescheduled eseményt.
  • A results.updated az 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 a results.fault mindig egy azonos results_revision értékű results.updated eseménnyel együtt érkezik. Az eredmények újranyílhatnak és újra lezárulhatnak, így második results.completed eseményt is kaphatsz.
Iratkozz fel a 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 és shipment.<status> eseményt küld azonos revision értékkel.

Payload

Státuszesemény adatai

appointment.confirmed

Eredményesemény adatai

home_kit_order.results.completed

Dokumentumtörlési esemény adatai

A document.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
A 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 a webhook-id, a webhook-timestamp (Unix- másodpercben) és a webhook-signature fejléc.
  1. Vedd a nyers kéréstörzset. A JSON feldolgozása előtt ellenőrizd.
  2. Állítsd össze az aláírt tartalmat: {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Dekódold base64-ből a titkos kulcsod whsec_ utáni részét. Ezt használd kulcsként.
  4. Számítsd ki az aláírt tartalom HMAC-SHA256 értékét, és kódold base64-be.
  5. Konstans időben hasonlítsd össze a webhook-signature minden v1,<signature> bejegyzésével. A bejegyzéseket szóközök választják el. Egyetlen egyezés elég.
  6. Utasítsd el a kérést, ha a webhook-timestamp több mint 5 perccel eltér az órádtól.
Node.js
A séma a Standard Webhooks. A legtöbb nyelvhez léteznek Standard Webhooks könyvtárak, amelyek ezt egyetlen hívással elvégzik.

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 a revoke_current_secret_now: true értéket a régi titkos kulcs azonnali érvénytelenítéséhez.

Kézbesítés

  • Válaszolj 2xx kó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ő https URL-t. Az Aniva nem követi az átirányításokat: a 3xx hibának számít.
  • A kézbesítés legalább egyszeri és nem sorrendhelyes. Szűrd ki a duplikátumokat a webhook-id alapján. A revíziók segítségével hagyd figyelmen kívül a régebbi eseményeket.
  • Válaszolj 410 Gone kó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 nem 2xx 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 webhook alert_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ány GET 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.
Ha azonnal értesülni szeretnél egy változásról, használd a táblázatban szereplő webhook-eseményeket.
  • 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 200 vá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 és updated_at mező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 és revision értéket. Hagyd figyelmen kívül az ennél alacsonyabb értékű eseményeket.
  • Kérd le az url címet. Az esemény azt jelzi, hogy valami megváltozott. A GET végpont mondja meg, mi.
  • Válaszolj gyorsan. Tedd sorba az eseményt, és válaszolj 2xx kóddal, mielőtt feldolgozod.
  • Egyeztess rendszeresen. Futtass rendszeres feladatot, amely a GET vé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.