Hopp til hovedinnhold
En webhook er en HTTPS-POST som Aniva sender til serveren din når noe endres. Du trenger ikke å polle. Hendelser er tynne. De inneholder objekt-ID-en, den nye statusen, en revisjon og url-en du skal lese. De inneholder aldri labverdier eller personopplysninger. Les url-en med API-nøkkelen din for å hente dataene.

Raskt oppsett

  1. Bygg et HTTPS-endepunkt som godtar POST og svarer med 2xx innen 15 sekunder.
  2. Registrer det med Opprett webhook. Lagre secret fra svaret. Aniva viser den bare én gang.
  3. Verifiser signaturen for hver forespørsel.
  4. Send en testhendelse. Sjekk resultatet i Vis leveringer.
API-nøkkelen din trenger scopet webhooks_manage. Be Aniva om å legge det til. En webhook tilhører API-nøkkelen som opprettet den, og en nøkkel kan eie maksimalt 5 webhooks.

Hendelser

Du mottar bare en hendelse for objekter API-nøkkelen din kan lese med det tilsvarende GET-endepunktet. Velg typene med enabled_events. Send ["*"] for å motta alle typer, også typer som legges til senere.
  • En statushendelse utløses ved hver overgang til den statusen, også ved en overgang tilbake. For eksempel sender et hjemmetestsett som går fra dispatched tilbake til pending, home_kit_order.pending.
  • Én endring kan sende to hendelser med samme status_revision, for eksempel appointment.confirmed og appointment.rescheduled.
  • results.updated utløses ved hver endring i resultatene: en ny verdi, en rettelse, en feil, et nytt eller erstattet dokument, eller en prøve som forlater objektet. Den kommer innen noen få minutter etter den siste endringen.
  • results.completed og results.fault kommer alltid sammen med en results.updated med samme results_revision. Resultater kan åpnes igjen og fullføres på nytt, så du kan få enda en results.completed.
Abonner på results.updated for å vise delresultater, eller på results.completed for bare å reagere på endelige resultater. results.completed følger resultatverdiene, ikke PDF-en. Rapport-PDF-en kan komme før eller etter verdiene. Noen laboratorier sender først en foreløpig PDF og erstatter den senere med den endelige under samme dokument-id. Erstatningen sender results.updated. Les documents[].original_file_name for å skille dem fra hverandre: Labor Quade avslutter en foreløpig rapport (Vorbefund) med _V og den endelige rapporten (Endbefund) med _E, for eksempel 7642100312_B0012_FA_E.pdf. Hendelser for sted, profil og forsendelse kommer innen noen få minutter. Aniva venter til objektet ikke har blitt endret på 2 minutter, slik at flere raske endringer sender én hendelse. Disse reglene gjelder også:
  • Anonyme profiler sender ingen hendelser.
  • En forsendelse sender ingen hendelse når du mister tilgang til den.
  • En statusendring for en forsendelse sender shipment.updated og shipment.<status>-hendelsen med samme revision.

Payload

Data for statushendelser

appointment.confirmed

Data for resultathendelser

home_kit_order.results.completed

Data for hendelser ved slettet dokument

document.deleted inneholder object (document), id, previous_results_status og results_revision. Den har ingen url, fordi det ikke er noe igjen å lese.
document.deleted

Data for steds-, profil- og forsendelseshendelser

shipment.in_transit
En ping inneholder data.object webhook og data.id, webhook-ID-en.

Verifiser signaturen

Hendelser inneholder ingen data, men du bør likevel verifisere hver enkelt. En gyldig signatur beviser at hendelsen kom fra Aniva. Hver forespørsel inneholder headerne webhook-id, webhook-timestamp (Unix-sekunder) og webhook-signature.
  1. Ta den rå forespørselskroppen. Verifiser den før du parser JSON-en.
  2. Sett sammen det signerte innholdet {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Base64-dekod delen av hemmeligheten din etter whsec_. Bruk den som nøkkel.
  4. Beregn HMAC-SHA256 av det signerte innholdet og kod det som base64.
  5. Sammenlign det i konstant tid med hver v1,<signature>-oppføring i webhook-signature. Oppføringene er skilt med mellomrom. Ett treff er nok.
  6. Avvis forespørselen når webhook-timestamp avviker med mer enn 5 minutter fra klokken din.
Node.js
Standarden er Standard Webhooks. Det finnes Standard Webhooks-biblioteker for de fleste språk som gjør dette i ett kall.

Roter hemmeligheten

Kall Roter hemmelighet for å få en ny hemmelighet. I 24 timer signerer Aniva med både den gamle og den nye hemmeligheten, så ta i bruk den nye innen den tiden. Etter en lekkasje sender du revoke_current_secret_now: true for å stoppe den gamle hemmeligheten med én gang.

Levering

  • Svar 2xx innen 15 sekunder. Lagre hendelsen eller legg den i kø, og gjør arbeidet senere.
  • Bruk en https-URL på port 443 med en offentlig vert. Aniva følger ikke omdirigeringer: et 3xx-svar regnes som en feil.
  • Levering skjer minst én gang og i vilkårlig rekkefølge. Forkast duplikater ved hjelp av webhook-id. Bruk revisjonene til å ignorere en eldre hendelse.
  • Svar 410 Gone for å stoppe hendelsene. Aniva deaktiverer webhooken med én gang.
  • Aniva lagrer leveringer i 30 dager. Etter det kan du ikke liste dem opp eller sende dem på nytt.

Nye forsøk

Et svar som ikke er 2xx, et tidsavbrudd eller en nettverksfeil starter et nytt forsøk. Hver hendelse får opptil 10 forsøk over omtrent tre dager: Etter forsøk 10 er leveringen failed. Send den på nytt med Send levering på nytt. Den beholder samme webhook-id.

Feilvarsler

Aniva sender e-post til webhookens alert_emails når ingen levering har lyktes på 24 timer, når en hendelse er failed, og når webhooken deaktiveres. Etter 5 dager uten en vellykket levering deaktiverer Aniva webhooken. En deaktivert webhook får ingen nye hendelser, og de ventende leveringene kanselleres. For å starte igjen fikser du endepunktet ditt og sender status: "enabled" med Oppdater webhook. Hendelser du gikk glipp av, sendes ikke på nytt av seg selv. Send dem på nytt, eller les gjeldende tilstand med GET-endepunktene.

Gjentatte lesinger

Aniva lagrer svaret fra enkelte GET-endepunkter i en kort periode. Når API-nøkkelen din sender samme forespørsel på nytt innenfor denne tiden, får du det lagrede svaret. Du får ingen feil, og svarkroppen har samme format.
  • Én oppføring (en forsendelse, en bestilling av hjemmetestsett, en time og resultatene av de to siste): ved hvert kall sjekker Aniva at oppføringen er uendret. Hvis den er endret, får du et ferskt svar.
  • En liste kan være eldre enn oppføringene den inneholder, høyst 5 minutter.
For å få vite om en endring med én gang, bruker du webhook-hendelsene i tabellen.
  • Samme forespørsel betyr samme API-nøkkel, samme endepunkt og samme spørringsparametere. En annen side i en liste er en annen forespørsel og får sitt eget svar.
  • Aniva lagrer bare 200-svar. En feil lagres aldri.
  • Tiden starter når Aniva lagrer svaret. Et senere kall forlenger den ikke.
  • Etter at API-nøkkelen din oppretter, oppdaterer, aktiverer eller kansellerer noe, er neste lesing fersk. Neste lesing av den oppføringen med en annen av dine API-nøkler er også fersk.
  • I et lagret forsendelsessvar kan feltene synced_at og updated_at være eldre enn i et ferskt svar. Status, sporing og adresser er oppdaterte.
  • I et lagret resultatsvar kan et biomarkørnavn, en enhet eller en omregnet verdi være opptil 60 minutter gammel etter at Aniva endrer katalogen sin. De målte verdiene er oppdaterte.
  • Etter at Aniva oppretter en webhook-hendelse for webhooken din, er neste lesing av den oppføringen, av resultatene dens og av listene dens fersk. Dermed viser lesingen som følger etter en hendelse, alltid endringen.

Svarheadere

Hvert svar fra disse endepunktene til en gyldig API-nøkkel har disse headerne:

Beste praksis

  • Forkast duplikater. Hopp over hendelser med en webhook-id du allerede har behandlet.
  • Bruk revisjonene. Lagre den høyeste verdien av status_revision, results_revision og revision per objekt. Ignorer hendelser med en lavere verdi.
  • Hent url. Hendelsen sier at noe er endret. GET-endepunktet sier hva.
  • Svar raskt. Legg hendelsen i kø og svar 2xx før du behandler den.
  • Avstem. Kjør en fast jobb som leser åpne objekter med GET-endepunktene. Polling er fortsatt en gyldig reserveløsning. En gjentatt lesing kan få et lagret svar, se Gjentatte lesinger.
  • Test etter hver utrulling. Bruk Send testhendelse.