POST, som Aniva sender til din server, når noget ændrer sig. Du behøver ikke
at polle.
Hændelser er kompakte. De indeholder objekt-id’et, den nye status, en revision og den url, der skal læses. De
indeholder aldrig laboratorieværdier eller persondata. Læs url med din API-nøgle for at hente dataene.
Hurtig opsætning
- Byg et HTTPS-endpoint, der accepterer
POSTog svarer2xxinden for 15 sekunder. - Registrer det med Opret webhook.
Gem
secretfra svaret. Aniva viser den kun én gang. - Verificer signaturen på hver forespørgsel.
- Send en testhændelse. Tjek resultatet i Vis leveringer.
webhooks_manage. Bed Aniva om at tilføje det. En webhook tilhører den
API-nøgle, der oprettede den, og en nøgle kan højst eje 5 webhooks.
Hændelser
Du modtager kun en hændelse for objekter, din API-nøgle kan læse med det tilsvarendeGET-endpoint.
Vælg typerne med enabled_events. Send ["*"] for at modtage alle typer, også typer der tilføjes senere.
- En statushændelse udløses ved hvert skift til den status, også ved et skift tilbage. For eksempel
sender et kit, der går fra
dispatchedtilbage tilpending,home_kit_order.pending. - Én ændring kan sende to hændelser med samme
status_revision, for eksempelappointment.confirmedogappointment.rescheduled. results.updatedudløses ved enhver ændring af resultaterne: en ny værdi, en rettelse, en fejl, et nyt eller udskiftet dokument eller en prøve, der forlader objektet. Den ankommer inden for få minutter efter den seneste ændring.results.completedogresults.faultkommer altid sammen med enresults.updatedmed sammeresults_revision. Resultater kan genåbnes og afsluttes igen, så du kan få endnu enresults.completed.
results.updated for at vise delvise resultater, eller på results.completed for kun at reagere på
endelige resultater.
results.completed følger resultatværdierne, ikke PDF’en. Rapport-PDF’en kan ankomme før eller
efter værdierne. Nogle laboratorier sender først en foreløbig PDF og erstatter den senere med den endelige
under samme dokument-id. Udskiftningen sender results.updated. Læs
documents[].original_file_name for at skelne mellem de to: Labor Quade afslutter en foreløbig rapport
(Vorbefund) med _V og den endelige rapport (Endbefund) med _E, for eksempel
7642100312_B0012_FA_E.pdf.
Lokations-, profil- og forsendelseshændelser ankommer inden for få minutter. Aniva venter, til objektet ikke har
ændret sig i 2 minutter, så en række hurtige redigeringer sender én hændelse. Disse regler gælder også:
- Anonyme profiler sender ingen hændelser.
- En forsendelse sender ingen hændelse, når du mister adgangen til den.
- En ændring i forsendelsesstatus sender
shipment.updatedog hændelsenshipment.<status>med sammerevision.
Payload
Data for statushændelser
appointment.confirmed
Data for resultathændelser
home_kit_order.results.completed
Data for hændelser om slettede dokumenter
document.deleted indeholder object (document), id, previous_results_status og
results_revision. Den har ingen url, fordi der ikke er noget tilbage at læse.
document.deleted
Data for lokations-, profil- og forsendelseshændelser
shipment.in_transit
ping indeholder data.object webhook og data.id, som er webhook-id’et.
Verificer signaturen
Hændelser indeholder ingen data, men du bør stadig verificere hver enkelt. En gyldig signatur beviser, at hændelsen kommer fra Aniva. Hver forespørgsel indeholder headernewebhook-id, webhook-timestamp (Unix-
sekunder) og webhook-signature.
- Tag den rå request body. Verificer den, før du parser JSON’en.
- Opbyg det signerede indhold
{webhook-id}.{webhook-timestamp}.{raw body}. - Base64-dekod den del af din hemmelighed, der kommer efter
whsec_. Brug den som nøgle. - Beregn HMAC-SHA256 for det signerede indhold, og kod det som base64.
- Sammenlign det i konstant tid med hvert
v1,<signature>-element iwebhook-signature. Elementerne er adskilt af mellemrum. Ét match er nok. - Afvis forespørgslen, hvis
webhook-timestampafviger mere end 5 minutter fra dit ur.
Node.js
Roter hemmeligheden
Kald Roter hemmelighed for at få en ny hemmelighed. I 24 timer signerer Aniva med både den gamle og den nye hemmelighed, så udrul den nye inden da. Sendrevoke_current_secret_now: true efter et læk for at stoppe den gamle hemmelighed med det samme.
Levering
- Svar med
2xxinden for 15 sekunder. Gem hændelsen, eller sæt den i kø, og behandl den senere. - Brug en
https-URL på port 443 med en offentlig vært. Aniva følger ikke omdirigeringer: en3xxtæller som en fejl. - Levering sker mindst én gang og uden fast rækkefølge. Filtrer dubletter fra via
webhook-id. Brug revisionerne til at ignorere en ældre hændelse. - Svar med
410 Gonefor at stoppe hændelserne. Aniva deaktiverer webhooken med det samme. - Aniva gemmer leveringer i 30 dage. Derefter kan du ikke vise eller sende dem igen.
Nye forsøg
Et andet svar end2xx, en timeout eller en netværksfejl udløser et nyt forsøg. Hver hændelse får op til 10 forsøg
over omkring tre dage:
Efter forsøg 10 er leveringen
failed. Send den igen med
Send levering igen. Den beholder det samme webhook-id.
Fejlmeddelelser
Aniva sender en e-mail til webhookensalert_emails, når ingen levering er lykkedes i 24 timer, når en hændelse er
failed, og når webhooken deaktiveres. Efter 5 dage uden en vellykket levering deaktiverer Aniva
webhooken. En deaktiveret webhook modtager ingen nye hændelser, og dens ventende leveringer
annulleres.
For at starte igen skal du rette dit endpoint og sende
status: "enabled" med
Opdater webhook. Manglende hændelser sendes ikke
igen af sig selv. Send dem igen, eller læs den aktuelle tilstand med GET-endpointsene.
Gentagne læsninger
Aniva gemmer svaret fra nogleGET-endpoints i kort tid. Når din API-nøgle sender den samme
forespørgsel igen inden for denne tid, får du det gemte svar. Du får ingen fejl, og body har det
samme format.
- En enkelt post (en forsendelse, en hjemmetestkit-ordre, en tid og resultaterne for de to sidstnævnte): Ved hvert kald tjekker Aniva, om posten er uændret. Hvis den er ændret, får du et nyt svar.
- En liste kan være ældre end sine poster, højst 5 minutter.
- Den samme forespørgsel vil sige den samme API-nøgle, det samme endpoint og de samme query-parametre. En anden side i en liste er en anden forespørgsel og får sit eget svar.
- Aniva gemmer kun et
200-svar. En fejl gemmes aldrig. - Tiden starter, når Aniva gemmer svaret. Et senere kald forlænger den ikke.
- Når din API-nøgle opretter, opdaterer, aktiverer eller annullerer noget, giver din næste læsning et nyt svar. Den næste læsning af den post med en anden af dine API-nøgler giver også et nyt svar.
- I et gemt svar for en forsendelse kan felterne
synced_atogupdated_atvære ældre end i et nyt svar. Status, sporing og adresser er aktuelle. - I et gemt svar med resultater kan et biomarkørnavn, en enhed eller en omregnet værdi være op til 60 minutter gammel, efter at Aniva ændrer sit katalog. De målte værdier er aktuelle.
- Når Aniva opretter en webhook-hændelse for din webhook, giver din næste læsning af den post, dens resultater og dens lister et nyt svar. Læsningen efter en hændelse viser derfor altid ændringen.
Svarheadere
Hvert svar fra disse endpoints til en gyldig API-nøgle indeholder disse headere:God praksis
- Frasorter dubletter. Spring en hændelse over, hvis du allerede har behandlet dens
webhook-id. - Brug revisionerne. Gem den højeste
status_revision,results_revisionogrevisionpr. objekt. Ignorer en hændelse med en lavere værdi. - Hent
url. Hændelsen fortæller, at noget er ændret.GET-endpointet fortæller hvad. - Svar hurtigt. Sæt hændelsen i kø, og svar med
2xx, før du behandler den. - Afstem løbende. Kør et fast job, der læser åbne objekter med
GET-endpointsene. Polling er fortsat en gyldig reserveløsning. En gentagen læsning kan give et gemt svar, se Gentagne læsninger. - Test efter hver udrulning. Brug Send testhændelse.