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
- Bygg et HTTPS-endepunkt som godtar
POSTog svarer med2xxinnen 15 sekunder. - Registrer det med Opprett webhook.
Lagre
secretfra svaret. Aniva viser den bare én gang. - Verifiser signaturen for hver forespørsel.
- Send en testhendelse. Sjekk resultatet i Vis leveringer.
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 tilsvarendeGET-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
dispatchedtilbake tilpending,home_kit_order.pending. - Én endring kan sende to hendelser med samme
status_revision, for eksempelappointment.confirmedogappointment.rescheduled. results.updatedutlø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.completedogresults.faultkommer alltid sammen med enresults.updatedmed sammeresults_revision. Resultater kan åpnes igjen og fullføres på nytt, så du kan få enda enresults.completed.
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.updatedogshipment.<status>-hendelsen med sammerevision.
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
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 headernewebhook-id, webhook-timestamp
(Unix-sekunder) og webhook-signature.
- Ta den rå forespørselskroppen. Verifiser den før du parser JSON-en.
- Sett sammen det signerte innholdet
{webhook-id}.{webhook-timestamp}.{raw body}. - Base64-dekod delen av hemmeligheten din etter
whsec_. Bruk den som nøkkel. - Beregn HMAC-SHA256 av det signerte innholdet og kod det som base64.
- Sammenlign det i konstant tid med hver
v1,<signature>-oppføring iwebhook-signature. Oppføringene er skilt med mellomrom. Ett treff er nok. - Avvis forespørselen når
webhook-timestampavviker med mer enn 5 minutter fra klokken din.
Node.js
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 durevoke_current_secret_now: true for å stoppe den gamle hemmeligheten med én gang.
Levering
- Svar
2xxinnen 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: et3xx-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 Gonefor å 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 er2xx, 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 webhookensalert_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 enkelteGET-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.
- 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_atogupdated_atvæ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-iddu allerede har behandlet. - Bruk revisjonene. Lagre den høyeste verdien av
status_revision,results_revisionogrevisionper 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
2xxfø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.