POST die Aniva naar jouw server stuurt wanneer er iets verandert. Je hoeft
niet te pollen.
Gebeurtenissen zijn licht. Ze bevatten het object-ID, de nieuwe status, een revisie en de url om uit te lezen. Ze
bevatten nooit labwaarden of persoonsgegevens. Lees de url uit met je API-sleutel om de gegevens op te halen.
Snel instellen
- Bouw een HTTPS-endpoint dat
POSTaccepteert en binnen 15 seconden met2xxantwoordt. - Registreer het met Webhook aanmaken.
Sla het
secretuit de response op. Aniva toont dit maar één keer. - Verifieer de handtekening van elk verzoek.
- Verstuur een testgebeurtenis. Controleer het resultaat in Leveringen weergeven.
webhooks_manage nodig. Vraag Aniva om deze toe te voegen. Een webhook hoort bij de
API-sleutel waarmee deze is aangemaakt, en een sleutel kan maximaal 5 webhooks hebben.
Events
Je ontvangt alleen een event voor objecten die je API-key kan lezen met het bijbehorendeGET-endpoint.
Kies de types met enabled_events. Stuur ["*"] om elk type te ontvangen, ook types die later worden toegevoegd.
- Een statusevent wordt verstuurd bij elke overgang naar die status, ook bij een stap terug. Een kit die
bijvoorbeeld van
dispatchedteruggaat naarpending, verstuurthome_kit_order.pending. - Eén wijziging kan twee events met dezelfde
status_revisionversturen, bijvoorbeeldappointment.confirmedenappointment.rescheduled. results.updatedwordt verstuurd bij elke wijziging van de resultaten: een nieuwe waarde, een correctie, een fout, een nieuw of vervangen document, of een monster dat het object verlaat. Het komt binnen enkele minuten na de laatste wijziging aan.results.completedenresults.faultkomen altijd samen met eenresults.updatedmet dezelfderesults_revision. Resultaten kunnen opnieuw worden geopend en opnieuw worden afgerond, dus je kunt een tweederesults.completedkrijgen.
results.updated om gedeeltelijke resultaten te tonen, of op results.completed om alleen op
definitieve resultaten te reageren.
results.completed volgt de resultaatwaarden, niet de pdf. De rapport-pdf kan voor of
na de waarden aankomen. Sommige labs sturen eerst een voorlopige pdf en vervangen deze later door de definitieve
onder hetzelfde document-id. De vervanging verstuurt results.updated. Lees
documents[].original_file_name om de twee uit elkaar te houden: Labor Quade eindigt een voorlopig rapport
(Vorbefund) op _V en het definitieve rapport (Endbefund) op _E, bijvoorbeeld
7642100312_B0012_FA_E.pdf.
Locatie-, profiel- en zendingsevents komen binnen enkele minuten aan. Aniva wacht tot het object
2 minuten niet is veranderd, zodat een reeks wijzigingen één event verstuurt. Deze regels gelden ook:
- Anonieme profielen versturen geen events.
- Een zending verstuurt geen event wanneer je de toegang ertoe verliest.
- Een statuswijziging van een zending verstuurt
shipment.updateden hetshipment.<status>-event met dezelfderevision.
Payload
Gegevens van statusevents
appointment.confirmed
Gegevens van resultatenevents
home_kit_order.results.completed
Gegevens van events voor verwijderde documenten
document.deleted bevat object (document), id, previous_results_status en
results_revision. Het heeft geen url, omdat er niets meer te lezen is.
document.deleted
Gegevens van locatie-, profiel- en zendingsevents
shipment.in_transit
ping bevat data.object webhook en data.id, het webhook-id.
De handtekening verifiëren
Events bevatten geen gegevens, maar je moet elk event toch verifiëren. Een geldige handtekening bewijst dat het event van Aniva komt. Elk verzoek bevat de headerswebhook-id, webhook-timestamp
(Unix-seconden) en webhook-signature.
- Neem de ruwe requestbody. Verifieer deze voordat je de JSON parset.
- Stel de ondertekende inhoud samen:
{webhook-id}.{webhook-timestamp}.{raw body}. - Decodeer het deel van je secret na
whsec_vanuit base64. Gebruik dit als sleutel. - Bereken de HMAC-SHA256 van de ondertekende inhoud en codeer deze als base64.
- Vergelijk deze in constante tijd met elke
v1,<signature>-waarde inwebhook-signature. De waarden zijn gescheiden door spaties. Eén overeenkomst is genoeg. - Wijs het verzoek af wanneer
webhook-timestampmeer dan 5 minuten afwijkt van je klok.
Node.js
Het secret roteren
Roep Secret roteren aan om een nieuw secret te krijgen. Aniva ondertekent 24 uur lang met het oude en het nieuwe secret, dus rol het nieuwe binnen die tijd uit. Stuur na een lekrevoke_current_secret_now: true om het oude secret direct te stoppen.
Aflevering
- Antwoord binnen 15 seconden met
2xx. Sla het event op of zet het in een wachtrij en verwerk het later. - Gebruik een
https-URL op poort 443 met een publieke host. Aniva volgt geen redirects: een3xxtelt als mislukt. - Aflevering gebeurt minstens één keer en niet op volgorde. Verwijder duplicaten op basis van
webhook-id. Gebruik de revisies om een ouder event te negeren. - Antwoord met
410 Goneom de events te stoppen. Aniva schakelt de webhook direct uit. - Aniva bewaart afleveringen 30 dagen. Daarna kun je ze niet meer opvragen of opnieuw verzenden.
Nieuwe pogingen
Een antwoord anders dan2xx, een time-out of een netwerkfout start een nieuwe poging. Elk event krijgt maximaal 10 pogingen
verspreid over ongeveer drie dagen:
Na poging 10 is de aflevering
failed. Verzend deze opnieuw met
Aflevering opnieuw verzenden. Deze behoudt dezelfde webhook-id.
Foutmeldingen
Aniva mailt dealert_emails van de webhook wanneer er 24 uur lang geen aflevering is geslaagd, wanneer een event
failed is en wanneer de webhook is uitgeschakeld. Na 5 dagen zonder geslaagde aflevering schakelt Aniva
de webhook uit. Een uitgeschakelde webhook krijgt geen nieuwe events en wachtende afleveringen worden
geannuleerd.
Om opnieuw te starten, herstel je je endpoint en stuur je
status: "enabled" met
Webhook bijwerken. Gemiste events worden niet
vanzelf opnieuw verstuurd. Verzend ze opnieuw of lees de huidige status met de GET-endpoints.
Herhaalde leesverzoeken
Aniva slaat het antwoord van sommigeGET-endpoints korte tijd op. Wanneer je API-sleutel hetzelfde
verzoek binnen deze tijd opnieuw stuurt, krijg je het opgeslagen antwoord. Je krijgt geen foutmelding en de body heeft
hetzelfde formaat.
- Eén record (een zending, een thuistestkitbestelling, een afspraak en de resultaten van de laatste twee): bij elke aanroep controleert Aniva of het record ongewijzigd is. Is het gewijzigd, dan krijg je een nieuw antwoord.
- Een lijst kan ouder zijn dan de records erin, maximaal 5 minuten.
- Hetzelfde verzoek betekent dezelfde API-sleutel, hetzelfde endpoint en dezelfde queryparameters. Een andere pagina van een lijst is een ander verzoek en krijgt een eigen antwoord.
- Aniva slaat alleen een
200-antwoord op. Een fout wordt nooit opgeslagen. - De tijd start zodra Aniva het antwoord opslaat. Een latere aanroep verlengt die tijd niet.
- Nadat je API-sleutel iets aanmaakt, bijwerkt, activeert of annuleert, krijgt je volgende leesverzoek een nieuw antwoord. Het volgende leesverzoek voor dat record met een andere API-sleutel van jou krijgt ook een nieuw antwoord.
- In een opgeslagen antwoord voor een zending kunnen de velden
synced_atenupdated_atouder zijn dan in een nieuw antwoord. Status, tracking en adressen zijn actueel. - In een opgeslagen antwoord met resultaten kunnen de naam van een biomarker, een eenheid of een omgerekende waarde tot 60 minuten oud zijn nadat Aniva de catalogus wijzigt. De gemeten waarden zijn actueel.
- Nadat Aniva een webhook-event voor je webhook aanmaakt, krijgt je volgende leesverzoek voor dat record, de resultaten ervan en de bijbehorende lijsten een nieuw antwoord. Het leesverzoek na een event toont dus altijd de wijziging.
Response-headers
Elk antwoord van deze endpoints aan een geldige API-sleutel bevat deze headers:Best practices
- Verwijder duplicaten. Sla een event over waarvan je de
webhook-idal hebt verwerkt. - Gebruik de revisies. Sla de hoogste
status_revision,results_revisionenrevisionper object op. Negeer een event met een lagere waarde. - Haal de
urlop. Het event geeft aan dat er iets is gewijzigd. HetGET-endpoint geeft aan wat. - Antwoord snel. Zet het event in een wachtrij en antwoord met
2xxvoordat je het verwerkt. - Synchroniseer regelmatig. Draai regelmatig een taak die openstaande objecten uitleest met de
GET-endpoints. Polling blijft een geldige terugvaloptie. Een herhaald leesverzoek kan een opgeslagen antwoord terugkrijgen, zie Herhaalde leesverzoeken. - Test na elke deploy. Gebruik Testevent verzenden.