Hoppa till huvudinnehåll
En webhook är en HTTPS 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

  1. Bygg en HTTPS-slutpunkt som tar emot POST och svarar med 2xx inom 15 sekunder.
  2. Registrera den med Skapa webhook. Spara secret från svaret. Aniva visar det bara en gång.
  3. Verifiera signaturen för varje begäran.
  4. Skicka en testhändelse. Kontrollera resultatet i Lista leveranser.
Din API-nyckel behöver scopet 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 motsvarande GET-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 dispatched tillbaka till pending skickar home_kit_order.pending.
  • En ändring kan skicka två händelser med samma status_revision, till exempel appointment.confirmed och appointment.rescheduled.
  • results.updated utlö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.completed och results.fault kommer alltid tillsammans med en results.updated med samma results_revision. Resultat kan öppnas igen och slutföras på nytt, så du kan få en andra results.completed.
Prenumerera på 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.updated och händelsen shipment.<status> med samma revision.

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
En 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 headrarna webhook-id, webhook-timestamp (Unix-sekunder) och webhook-signature.
  1. Ta förfrågans råa body. Verifiera den innan du tolkar JSON.
  2. Skapa det signerade innehållet {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Base64-avkoda den del av din hemlighet som kommer efter whsec_. Använd den som nyckel.
  4. Beräkna HMAC-SHA256 för det signerade innehållet och koda det som base64.
  5. Jämför det i konstant tid med varje v1,<signature>-post i webhook-signature. Posterna separeras med mellanslag. En träff räcker.
  6. Avvisa förfrågan när webhook-timestamp skiljer sig mer än 5 minuter från din klocka.
Node.js
Specifikationen är Standard Webhooks. Bibliotek för Standard Webhooks finns för de flesta språk och gör detta i ett anrop.

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 du revoke_current_secret_now: true för att stoppa den gamla hemligheten direkt.

Leverans

  • Svara med 2xx inom 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: 3xx rä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 Gone fö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 än 2xx, 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 webhookens alert_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 vissa GET-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.
För att få veta om en ändring direkt använder du webhook-händelserna i tabellen.
  • 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_at och updated_at vara ä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-id du redan har bearbetat.
  • Använd revisionerna. Lagra högsta status_revision, results_revision och revision per 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 2xx innan 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.