Naar hoofdinhoud gaan
Een webhook is een HTTPS 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

  1. Bouw een HTTPS-endpoint dat POST accepteert en binnen 15 seconden met 2xx antwoordt.
  2. Registreer het met Webhook aanmaken. Sla het secret uit de response op. Aniva toont dit maar één keer.
  3. Verifieer de handtekening van elk verzoek.
  4. Verstuur een testgebeurtenis. Controleer het resultaat in Leveringen weergeven.
Je API-sleutel heeft de scope 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 bijbehorende GET-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 dispatched teruggaat naar pending, verstuurt home_kit_order.pending.
  • Eén wijziging kan twee events met dezelfde status_revision versturen, bijvoorbeeld appointment.confirmed en appointment.rescheduled.
  • results.updated wordt 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.completed en results.fault komen altijd samen met een results.updated met dezelfde results_revision. Resultaten kunnen opnieuw worden geopend en opnieuw worden afgerond, dus je kunt een tweede results.completed krijgen.
Abonneer je op 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.updated en het shipment.<status>-event met dezelfde revision.

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
Een 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 headers webhook-id, webhook-timestamp (Unix-seconden) en webhook-signature.
  1. Neem de ruwe requestbody. Verifieer deze voordat je de JSON parset.
  2. Stel de ondertekende inhoud samen: {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Decodeer het deel van je secret na whsec_ vanuit base64. Gebruik dit als sleutel.
  4. Bereken de HMAC-SHA256 van de ondertekende inhoud en codeer deze als base64.
  5. Vergelijk deze in constante tijd met elke v1,<signature>-waarde in webhook-signature. De waarden zijn gescheiden door spaties. Eén overeenkomst is genoeg.
  6. Wijs het verzoek af wanneer webhook-timestamp meer dan 5 minuten afwijkt van je klok.
Node.js
Het schema is Standard Webhooks. Voor de meeste talen bestaan Standard Webhooks-bibliotheken die dit in één aanroep doen.

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 lek revoke_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: een 3xx telt 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 Gone om 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 dan 2xx, 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 de alert_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 sommige GET-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.
Gebruik de webhook-events in de tabel om direct op de hoogte te zijn van een wijziging.
  • 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_at en updated_at ouder 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-id al hebt verwerkt.
  • Gebruik de revisies. Sla de hoogste status_revision, results_revision en revision per object op. Negeer een event met een lagere waarde.
  • Haal de url op. Het event geeft aan dat er iets is gewijzigd. Het GET-endpoint geeft aan wat.
  • Antwoord snel. Zet het event in een wachtrij en antwoord met 2xx voordat 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.