Siirry pääsisältöön
Webhook on HTTPS POST -pyyntö, jonka Aniva lähettää palvelimellesi, kun jokin muuttuu. Sinun ei tarvitse kysellä muutoksia toistuvasti. Tapahtumat ovat kevyitä. Ne sisältävät kohteen tunnisteen, uuden tilan, version ja luettavan url-osoitteen. Ne eivät koskaan sisällä laboratorioarvoja tai henkilötietoja. Hae tiedot lukemalla url API-avaimellasi.

Pikakäyttöönotto

  1. Rakenna HTTPS-päätepiste, joka ottaa vastaan POST-pyyntöjä ja vastaa 2xx-koodilla 15 sekunnin kuluessa.
  2. Rekisteröi se toiminnolla Luo webhook. Tallenna vastauksen secret. Aniva näyttää sen vain kerran.
  3. Tarkista allekirjoitus jokaisesta pyynnöstä.
  4. Lähetä testitapahtuma. Tarkista tulos kohdasta Listaa toimitukset.
API-avaimesi tarvitsee webhooks_manage-käyttöoikeuden. Pyydä Anivaa lisäämään se. Webhook kuuluu sen luoneelle API-avaimelle, ja yhdellä avaimella voi olla enintään 5 webhookia.

Tapahtumat

Saat tapahtuman vain objekteista, joita API-avaimesi voi lukea vastaavalla GET-päätepisteellä. Valitse tyypit enabled_events-kentällä. Lähetä ["*"], niin saat kaikki tyypit, myös myöhemmin lisätyt.
  • Tilatapahtuma lähetetään jokaisesta siirtymästä kyseiseen tilaan, myös paluusta takaisin. Esimerkiksi kotitestipakkaus, joka palaa tilasta dispatched tilaan pending, lähettää tapahtuman home_kit_order.pending.
  • Yksi muutos voi lähettää kaksi tapahtumaa samalla status_revision-arvolla, esimerkiksi appointment.confirmed ja appointment.rescheduled.
  • results.updated lähetetään jokaisesta tulosten muutoksesta: uudesta arvosta, korjauksesta, virheestä, uudesta tai korvatusta dokumentista tai näytteestä, joka poistuu objektista. Se saapuu muutaman minuutin kuluessa viimeisimmästä muutoksesta.
  • results.completed ja results.fault tulevat aina yhdessä results.updated-tapahtuman kanssa, jolla on sama results_revision. Tulokset voidaan avata uudelleen ja merkitä jälleen valmiiksi, joten voit saada toisen results.completed-tapahtuman.
Tilaa results.updated, jos haluat näyttää osittaiset tulokset, tai results.completed, jos haluat reagoida vain lopullisiin tuloksiin. results.completed seuraa tulosarvoja, ei PDF-tiedostoa. Raportin PDF voi saapua ennen arvoja tai niiden jälkeen. Jotkin laboratoriot lähettävät ensin alustavan PDF-tiedoston ja korvaavat sen myöhemmin lopullisella samalla dokumentin id-tunnuksella. Korvaaminen lähettää tapahtuman results.updated. Erota nämä kaksi toisistaan lukemalla documents[].original_file_name: Labor Quade päättää alustavan raportin (Vorbefund) merkintään _V ja lopullisen raportin (Endbefund) merkintään _E, esimerkiksi 7642100312_B0012_FA_E.pdf. Toimipiste-, profiili- ja lähetystapahtumat saapuvat muutaman minuutin kuluessa. Aniva odottaa, kunnes objekti ei ole muuttunut 2 minuuttiin, joten sarja muokkauksia lähettää yhden tapahtuman. Myös nämä säännöt pätevät:
  • Anonyymit profiilit eivät lähetä tapahtumia.
  • Lähetys ei lähetä tapahtumaa, kun menetät pääsyn siihen.
  • Lähetyksen tilan muutos lähettää tapahtuman shipment.updated ja tapahtuman shipment.<status> samalla revision-arvolla.

Tietosisältö

Tilatapahtuman tiedot

appointment.confirmed

Tulostapahtuman tiedot

home_kit_order.results.completed

Dokumentin poistotapahtuman tiedot

document.deleted sisältää kentät object (document), id, previous_results_status ja results_revision. Siinä ei ole url-kenttää, koska mitään luettavaa ei ole jäljellä.
document.deleted

Toimipiste-, profiili- ja lähetystapahtuman tiedot

shipment.in_transit
ping sisältää kentän data.object arvolla webhook ja kentän data.id, joka on webhookin tunnus.

Vahvista allekirjoitus

Tapahtumat eivät sisällä dataa, mutta jokainen niistä kannattaa silti vahvistaa. Kelvollinen allekirjoitus todistaa, että tapahtuma tuli Anivalta. Jokainen pyyntö sisältää otsakkeet webhook-id, webhook-timestamp (Unix- sekunteina) ja webhook-signature.
  1. Ota pyynnön raakarunko. Vahvista se ennen JSON:n jäsentämistä.
  2. Muodosta allekirjoitettava sisältö {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Dekoodaa salaisuutesi whsec_-etuliitteen jälkeinen osa base64-muodosta. Käytä sitä avaimena.
  4. Laske allekirjoitettavan sisällön HMAC-SHA256 ja koodaa se base64-muotoon.
  5. Vertaa sitä vakioajassa jokaiseen webhook-signature-otsakkeen v1,<signature>-merkintään. Merkinnät erotetaan välilyönneillä. Yksi osuma riittää.
  6. Hylkää pyyntö, jos webhook-timestamp eroaa kellostasi yli 5 minuuttia.
Node.js
Menetelmänä on Standard Webhooks. Useimmille kielille on Standard Webhooks -kirjastoja, jotka tekevät tämän yhdellä kutsulla.

Kierrätä salaisuus

Kutsu Vaihda salaisuus -päätepistettä saadaksesi uuden salaisuuden. Aniva allekirjoittaa 24 tunnin ajan sekä vanhalla että uudella salaisuudella, joten ota uusi käyttöön sen aikana. Vuodon jälkeen lähetä revoke_current_secret_now: true poistaaksesi vanhan salaisuuden käytöstä heti.

Toimitus

  • Vastaa 2xx-koodilla 15 sekunnin kuluessa. Tallenna tapahtuma tai lisää se jonoon ja käsittele se myöhemmin.
  • Käytä julkisen palvelimen https-URL-osoitetta portissa 443. Aniva ei seuraa uudelleenohjauksia: 3xx lasketaan virheeksi.
  • Toimitus tapahtuu vähintään kerran ilman taattua järjestystä. Hylkää kaksoiskappaleet webhook-id-tunnisteen avulla. Ohita vanhempi tapahtuma revisioiden avulla.
  • Vastaa 410 Gone lopettaaksesi tapahtumat. Aniva poistaa webhookin käytöstä heti.
  • Aniva säilyttää toimitukset 30 päivää. Sen jälkeen et voi listata tai lähettää niitä uudelleen.

Uudelleenyritykset

Muu kuin 2xx-vastaus, aikakatkaisu tai verkkovirhe käynnistää uudelleenyrityksen. Kutakin tapahtumaa yritetään enintään 10 kertaa noin kolmen päivän aikana: Yrityksen 10 jälkeen toimituksen tila on failed. Lähetä se uudelleen Lähetä toimitus uudelleen -päätepisteellä. Sen webhook-id pysyy samana.

Virheilmoitukset

Aniva lähettää sähköpostia webhookin alert_emails-osoitteisiin, kun yksikään toimitus ei ole onnistunut 24 tuntiin, kun tapahtuman tila on failed ja kun webhook poistetaan käytöstä. Kun 5 päivää on kulunut ilman onnistunutta toimitusta, Aniva poistaa webhookin käytöstä. Käytöstä poistettu webhook ei saa uusia tapahtumia, ja sen odottavat toimitukset perutaan. Aloita uudelleen korjaamalla päätepisteesi ja lähettämällä status: "enabled" Päivitä webhook -päätepisteellä. Väliin jääneitä tapahtumia ei lähetetä uudelleen automaattisesti. Lähetä ne uudelleen tai lue nykytila GET-päätepisteistä.

Toistuvat haut

Aniva tallentaa joidenkin GET-päätepisteiden vastauksen lyhyeksi ajaksi. Kun API-avaimesi lähettää saman pyynnön uudelleen tämän ajan kuluessa, saat tallennetun vastauksen. Et saa virhettä, ja vastauksen runko on samassa muodossa.
  • Yksi tietue (lähetys, kotitestipakkaustilaus, ajanvaraus ja kahden viimeksi mainitun tulokset): Aniva tarkistaa jokaisella kutsulla, ettei tietue ole muuttunut. Jos se on muuttunut, saat tuoreen vastauksen.
  • Lista voi olla vanhempi kuin sen tietueet, enintään 5 minuuttia.
Saat tiedon muutoksesta heti käyttämällä taulukon webhook-tapahtumia.
  • Sama pyyntö tarkoittaa samaa API-avainta, samaa päätepistettä ja samoja kyselyparametreja. Listan toinen sivu on eri pyyntö ja saa oman vastauksensa.
  • Aniva tallentaa vain 200-vastauksen. Virhettä ei tallenneta koskaan.
  • Aika alkaa, kun Aniva tallentaa vastauksen. Myöhempi kutsu ei pidennä sitä.
  • Kun API-avaimesi luo, päivittää, aktivoi tai peruu jotakin, seuraava hakusi on tuore. Myös toisella API-avaimellasi tehty seuraava haku kyseisestä tietueesta on tuore.
  • Tallennetussa lähetysvastauksessa kentät synced_at ja updated_at voivat olla vanhempia kuin tuoreessa vastauksessa. Tila, seuranta ja osoitteet ovat ajantasaisia.
  • Tallennetussa tulosvastauksessa biomarkkerin nimi, yksikkö tai muunnettu arvo voi olla enintään 60 minuuttia vanha sen jälkeen, kun Aniva muuttaa luetteloaan. Mitatut arvot ovat ajantasaisia.
  • Kun Aniva luo webhook-tapahtuman webhookillesi, seuraava kyseisen tietueen, sen tulosten ja sen listojen haku on tuore. Näin tapahtumaa seuraava haku näyttää aina muutoksen.

Vastausotsakkeet

Jokaisessa näiden päätepisteiden vastauksessa kelvolliselle API-avaimelle on nämä otsakkeet:

Parhaat käytännöt

  • Hylkää kaksoiskappaleet. Ohita tapahtuma, jonka webhook-id-tunnisteen olet jo käsitellyt.
  • Käytä revisioita. Tallenna suurin status_revision, results_revision ja revision kohdekohtaisesti. Ohita tapahtuma, jossa arvo on pienempi.
  • Hae url. Tapahtuma kertoo, että jokin muuttui. GET-päätepiste kertoo, mikä muuttui.
  • Vastaa nopeasti. Lisää tapahtuma jonoon ja vastaa 2xx-koodilla ennen sen käsittelyä.
  • Täsmäytä. Aja säännöllinen tehtävä, joka lukee avoimet kohteet GET-päätepisteistä. Kysely pysyy kelvollisena vararatkaisuna. Toistuva haku voi saada tallennetun vastauksen, katso Toistuvat haut.
  • Testaa jokaisen julkaisun jälkeen. Käytä Lähetä testitapahtuma -päätepistettä.