Spring til hovedindhold
En webhook er en HTTPS 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

  1. Byg et HTTPS-endpoint, der accepterer POST og svarer 2xx inden for 15 sekunder.
  2. Registrer det med Opret webhook. Gem secret fra svaret. Aniva viser den kun én gang.
  3. Verificer signaturen på hver forespørgsel.
  4. Send en testhændelse. Tjek resultatet i Vis leveringer.
Din API-nøgle skal have scopet 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 tilsvarende GET-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 dispatched tilbage til pending, home_kit_order.pending.
  • Én ændring kan sende to hændelser med samme status_revision, for eksempel appointment.confirmed og appointment.rescheduled.
  • results.updated udlø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.completed og results.fault kommer altid sammen med en results.updated med samme results_revision. Resultater kan genåbnes og afsluttes igen, så du kan få endnu en results.completed.
Abonner på 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.updated og hændelsen shipment.<status> med samme revision.

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
En 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 headerne webhook-id, webhook-timestamp (Unix- sekunder) og webhook-signature.
  1. Tag den rå request body. Verificer den, før du parser JSON’en.
  2. Opbyg det signerede indhold {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Base64-dekod den del af din hemmelighed, der kommer efter whsec_. Brug den som nøgle.
  4. Beregn HMAC-SHA256 for det signerede indhold, og kod det som base64.
  5. Sammenlign det i konstant tid med hvert v1,<signature>-element i webhook-signature. Elementerne er adskilt af mellemrum. Ét match er nok.
  6. Afvis forespørgslen, hvis webhook-timestamp afviger mere end 5 minutter fra dit ur.
Node.js
Standarden er Standard Webhooks. Der findes Standard Webhooks-biblioteker til de fleste sprog, som klarer dette i ét kald.

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. Send revoke_current_secret_now: true efter et læk for at stoppe den gamle hemmelighed med det samme.

Levering

  • Svar med 2xx inden 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: en 3xx tæ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 Gone for 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 end 2xx, 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 webhookens alert_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 nogle GET-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.
Brug webhook-hændelserne i tabellen for at få besked om en ændring med det samme.
  • 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_at og updated_at væ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_revision og revision pr. 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.