POST som Aniva skickar till din server när något ändras. Du behöver inte
polla.
Händelser är tunna. De innehåller objektets ID, den nya statusen, en revision och den url som ska
läsas. De innehåller aldrig labbvärden eller personuppgifter. Läs url med din API-nyckel för att
hämta datan.
Snabbstart
- Bygg en HTTPS-slutpunkt som tar emot
POSToch svarar med2xxinom 15 sekunder. - Registrera den med Skapa webhook.
Spara
secretfrån svaret. Aniva visar det bara en gång. - Verifiera signaturen för varje begäran.
- Skicka en testhändelse. Kontrollera resultatet i Lista leveranser.
webhooks_manage. Be Aniva att lägga till det. En webhook tillhör den
API-nyckel som skapade den, och en nyckel kan äga högst 5 webhooks.
Händelser
Du får bara en händelse för objekt som din API-nyckel kan läsa med motsvarandeGET-endpoint.
Välj typer med enabled_events. Skicka ["*"] för att ta emot alla typer, även typer som läggs till senare.
- En statushändelse utlöses vid varje övergång till den statusen, även vid en återgång. Ett kit som till exempel
går från
dispatchedtillbaka tillpendingskickarhome_kit_order.pending. - En ändring kan skicka två händelser med samma
status_revision, till exempelappointment.confirmedochappointment.rescheduled. results.updatedutlöses vid varje ändring av resultaten: ett nytt värde, en rättelse, ett fel, ett nytt eller utbytt dokument, eller ett prov som lämnar objektet. Den kommer inom några minuter efter den senaste ändringen.results.completedochresults.faultkommer alltid tillsammans med enresults.updatedmed sammaresults_revision. Resultat kan öppnas igen och slutföras på nytt, så du kan få en andraresults.completed.
results.updated för att visa delresultat, eller på results.completed för att bara agera på
slutgiltiga resultat.
results.completed följer resultatvärdena, inte PDF-filen. Rapportens PDF kan komma före eller
efter värdena. Vissa labb skickar först en preliminär PDF och ersätter den senare med den slutgiltiga
under samma dokument-id. Utbytet skickar results.updated. Läs
documents[].original_file_name för att skilja dem åt: Labor Quade avslutar en preliminär rapport
(Vorbefund) med _V och den slutgiltiga rapporten (Endbefund) med _E, till exempel
7642100312_B0012_FA_E.pdf.
Händelser för platser, profiler och försändelser kommer inom några minuter. Aniva väntar tills objektet inte
har ändrats på 2 minuter, så en följd av ändringar skickar en händelse. Dessa regler gäller också:
- Anonyma profiler skickar inga händelser.
- En försändelse skickar ingen händelse när du förlorar åtkomst till den.
- En statusändring för en försändelse skickar
shipment.updatedoch händelsenshipment.<status>med sammarevision.
Payload
Data för statushändelser
appointment.confirmed
Data för resultathändelser
home_kit_order.results.completed
Data för händelser om borttagna dokument
document.deleted innehåller object (document), id, previous_results_status och
results_revision. Den har ingen url, eftersom det inte finns något kvar att läsa.
document.deleted
Data för plats-, profil- och försändelsehändelser
shipment.in_transit
ping innehåller data.object webhook och data.id, webhookens id.
Verifiera signaturen
Händelser innehåller ingen data, men du bör ändå verifiera varje händelse. En giltig signatur bevisar att händelsen kommer från Aniva. Varje förfrågan innehåller headrarnawebhook-id, webhook-timestamp (Unix-sekunder)
och webhook-signature.
- Ta förfrågans råa body. Verifiera den innan du tolkar JSON.
- Skapa det signerade innehållet
{webhook-id}.{webhook-timestamp}.{raw body}. - Base64-avkoda den del av din hemlighet som kommer efter
whsec_. Använd den som nyckel. - Beräkna HMAC-SHA256 för det signerade innehållet och koda det som base64.
- Jämför det i konstant tid med varje
v1,<signature>-post iwebhook-signature. Posterna separeras med mellanslag. En träff räcker. - Avvisa förfrågan när
webhook-timestampskiljer sig mer än 5 minuter från din klocka.
Node.js
Rotera hemligheten
Anropa Rotera hemlighet för att få en ny hemlighet. I 24 timmar signerar Aniva med både den gamla och den nya hemligheten, så driftsätt den nya inom den tiden. Efter en läcka skickar durevoke_current_secret_now: true för att stoppa den gamla hemligheten direkt.
Leverans
- Svara med
2xxinom 15 sekunder. Lagra eller köa händelsen och gör arbetet senare. - Använd en
https-URL på port 443 med en publik värd. Aniva följer inte omdirigeringar:3xxräknas som ett fel. - Leveransen sker minst en gång och utan garanterad ordning. Filtrera bort dubbletter med
webhook-id. Använd revisionerna för att ignorera en äldre händelse. - Svara med
410 Goneför att stoppa händelserna. Aniva inaktiverar webhooken direkt. - Aniva sparar leveranser i 30 dagar. Efter det kan du inte lista eller skicka dem igen.
Omförsök
Ett annat svar än2xx, en timeout eller ett nätverksfel startar ett omförsök. Varje händelse får upp till 10 försök
under ungefär tre dagar:
Efter försök 10 är leveransen
failed. Skicka den igen med
Skicka leverans igen. Den behåller samma webhook-id.
Felaviseringar
Aniva mejlar webhookensalert_emails när ingen leverans har lyckats på 24 timmar, när en händelse är
failed och när webhooken inaktiveras. Efter 5 dagar utan en lyckad leverans inaktiverar Aniva
webhooken. En inaktiverad webhook får inga nya händelser, och dess väntande leveranser
avbryts.
För att starta igen åtgärdar du din slutpunkt och skickar
status: "enabled" med
Uppdatera webhook. Missade händelser skickas inte
igen av sig själva. Skicka dem igen, eller läs det aktuella tillståndet med GET-slutpunkterna.
Upprepade läsningar
Aniva lagrar svaret från vissaGET-slutpunkter under en kort tid. När din API-nyckel skickar samma
begäran igen inom den tiden får du det lagrade svaret. Du får inget fel, och svarskroppen har
samma format.
- En post (en försändelse, en beställning av hemtestkit, en bokning och resultaten för de två sista): vid varje anrop kontrollerar Aniva att posten är oförändrad. Om den har ändrats får du ett färskt svar.
- En lista kan vara äldre än sina poster, högst 5 minuter.
- Samma begäran innebär samma API-nyckel, samma slutpunkt och samma frågeparametrar. En annan sida i en lista är en annan begäran och får ett eget svar.
- Aniva lagrar bara
200-svar. Ett fel lagras aldrig. - Tiden börjar när Aniva lagrar svaret. Ett senare anrop förlänger den inte.
- När din API-nyckel har skapat, uppdaterat, aktiverat eller avbrutit något blir din nästa läsning färsk. Nästa läsning av den posten med en annan av dina API-nycklar blir också färsk.
- I ett lagrat försändelsesvar kan fälten
synced_atochupdated_atvara äldre än i ett färskt svar. Status, spårning och adresser är aktuella. - I ett lagrat resultatsvar kan ett biomarkörnamn, en enhet eller ett konverterat värde vara upp till 60 minuter gammalt efter att Aniva ändrat sin katalog. De uppmätta värdena är aktuella.
- När Aniva skapar en webhook-händelse för din webhook blir nästa läsning av den posten, av dess resultat och av dess listor färsk. Läsningen som följer efter en händelse visar därför alltid ändringen.
Svarsheaders
Varje svar från dessa slutpunkter till en giltig API-nyckel har dessa headers:Bästa praxis
- Filtrera bort dubbletter. Hoppa över en händelse vars
webhook-iddu redan har bearbetat. - Använd revisionerna. Lagra högsta
status_revision,results_revisionochrevisionper objekt. Ignorera en händelse med ett lägre värde. - Hämta
url. Händelsen talar om att något har ändrats.GET-slutpunkten talar om vad. - Svara snabbt. Köa händelsen och svara med
2xxinnan du bearbetar den. - Stäm av. Kör ett regelbundet jobb som läser öppna objekt med
GET-slutpunkterna. Polling är fortfarande en giltig reservlösning. En upprepad läsning kan ge ett lagrat svar, se Upprepade läsningar. - Testa efter varje driftsättning. Använd Skicka testhändelse.