POST que Aniva envia al teu servidor quan canvia alguna cosa. No
cal que facis consultes periòdiques.
Els esdeveniments són lleugers. Porten l’ID de l’objecte, el nou estat, una revisió i la url per
llegir. No porten mai valors de laboratori ni dades personals. Llegeix la url amb la teva clau
d’API per obtenir les dades.
Configuració ràpida
- Crea un punt final HTTPS que accepti
POSTi respongui2xxen un màxim de 15 segons. - Registra’l amb Crear un webhook.
Desa el
secretde la resposta. Aniva només el mostra una vegada. - Verifica la signatura de cada petició.
- Envia un esdeveniment de prova. Comprova el resultat a Llistar lliuraments.
webhooks_manage. Demana a Aniva que l’afegeixi. Un webhook
pertany a la clau d’API que l’ha creat, i una clau pot tenir com a màxim 5 webhooks.
Esdeveniments
Només reps un esdeveniment per als objectes que la teva clau d’API pot llegir amb l’endpointGET corresponent.
Tria els tipus amb enabled_events. Envia ["*"] per rebre tots els tipus, també els que s’afegeixin més endavant.
- Un esdeveniment d’estat s’activa cada vegada que es passa a aquell estat, també si es torna enrere. Per exemple, un kit que
torna de
dispatchedapendingenviahome_kit_order.pending. - Un sol canvi pot enviar dos esdeveniments amb la mateixa
status_revision, per exempleappointment.confirmediappointment.rescheduled. results.updateds’activa amb cada canvi dels resultats: un valor nou, una correcció, un error, un document nou o substituït, o una mostra que surt de l’objecte. Arriba al cap d’uns minuts de l’últim canvi.results.completediresults.faultsempre arriben amb unresults.updatedde la mateixaresults_revision. Els resultats es poden reobrir i tornar a completar, així que pots rebre un segonresults.completed.
results.updated per mostrar resultats parcials, o a results.completed per actuar només amb
els resultats finals.
results.completed segueix els valors dels resultats, no el PDF. El PDF de l’informe pot arribar abans o
després dels valors. Alguns laboratoris envien primer un PDF preliminar i més tard el substitueixen pel final
amb el mateix id de document. La substitució envia results.updated. Llegeix
documents[].original_file_name per distingir-los: Labor Quade acaba l’informe preliminar
(Vorbefund) en _V i l’informe final (Endbefund) en _E, per exemple
7642100312_B0012_FA_E.pdf.
Els esdeveniments d’ubicació, perfil i enviament arriben al cap d’uns minuts. Aniva espera que l’objecte no hagi
canviat durant 2 minuts, així que un seguit d’edicions envia un sol esdeveniment. També s’apliquen aquestes regles:
- Els perfils anònims no envien cap esdeveniment.
- Un enviament no envia cap esdeveniment quan hi perds l’accés.
- Un canvi d’estat d’un enviament envia
shipment.updatedi l’esdevenimentshipment.<status>amb la mateixarevision.
Payload
Dades dels esdeveniments d’estat
appointment.confirmed
Dades dels esdeveniments de resultats
home_kit_order.results.completed
Dades de l’esdeveniment d’eliminació de document
document.deleted inclou object (document), id, previous_results_status i
results_revision. No té url, perquè ja no queda res per llegir.
document.deleted
Dades dels esdeveniments d’ubicació, perfil i enviament
shipment.in_transit
ping inclou data.object webhook i data.id, l’ID del webhook.
Verifica la signatura
Els esdeveniments no contenen dades, però tot i així hauries de verificar-ne cadascun. Una signatura vàlida demostra que l’esdeveniment prové d’Aniva. Cada petició inclou les capçalereswebhook-id, webhook-timestamp (segons
Unix) i webhook-signature.
- Agafa el cos en brut de la petició. Verifica’l abans d’analitzar el JSON.
- Construeix el contingut signat
{webhook-id}.{webhook-timestamp}.{raw body}. - Descodifica en base64 la part del teu secret després de
whsec_. Fes-la servir com a clau. - Calcula l’HMAC-SHA256 del contingut signat i codifica’l en base64.
- Compara’l en temps constant amb cada entrada
v1,<signature>dewebhook-signature. Les entrades estan separades per espais. Amb una coincidència n’hi ha prou. - Rebutja la petició quan
webhook-timestampdifereixi en més de 5 minuts del teu rellotge.
Node.js
Rota el secret
Crida Rota el secret per obtenir un secret nou. Durant 24 hores, Aniva signa amb el secret antic i amb el nou, així que desplega el nou dins d’aquest termini. Després d’una filtració, enviarevoke_current_secret_now: true per aturar el secret antic a l’instant.
Lliurament
- Respon amb
2xxen 15 segons com a màxim. Desa l’esdeveniment o posa’l en cua i fes la feina més tard. - Fes servir un URL
httpsal port 443 amb un amfitrió públic. Aniva no segueix les redireccions: un3xxcompta com un error. - El lliurament és com a mínim una vegada i sense ordre. Descarta els duplicats per
webhook-id. Fes servir les revisions per ignorar un esdeveniment anterior. - Respon amb
410 Goneper aturar els esdeveniments. Aniva desactiva el webhook a l’instant. - Aniva desa els lliuraments durant 30 dies. Després d’això, no els pots llistar ni tornar a enviar.
Reintents
Una resposta diferent de2xx, un temps d’espera exhaurit o un error de xarxa inicia un reintent. Cada esdeveniment té fins a 10 intents
durant uns tres dies:
Després de l’intent 10, el lliurament passa a
failed. Torna’l a enviar amb
Torna a enviar el lliurament. Manté el mateix webhook-id.
Avisos d’error
Aniva envia un correu electrònic alsalert_emails del webhook quan no hi ha hagut cap lliurament reeixit durant 24 hores, quan un esdeveniment és
failed i quan es desactiva el webhook. Després de 5 dies sense cap lliurament reeixit, Aniva
desactiva el webhook. Un webhook desactivat no rep esdeveniments nous i els seus lliuraments pendents es
cancel·len.
Per tornar a començar, corregeix el teu endpoint i envia
status: "enabled" amb
Actualitza el webhook. Els esdeveniments perduts no es tornen
a enviar sols. Torna’ls a enviar o llegeix l’estat actual amb els endpoints GET.
Lectures repetides
Aniva desa la resposta d’alguns endpointsGET durant una estona. Quan la teva clau API torna a enviar la mateixa
sol·licitud dins d’aquest temps, reps la resposta desada. No reps cap error i el cos té el
mateix format.
- Un registre (un enviament, una comanda de kit de prova a casa, una cita i els resultats dels dos últims): en cada crida, Aniva comprova que el registre no hagi canviat. Si ha canviat, reps una resposta nova.
- Una llista pot ser més antiga que els seus registres, com a màxim 5 minuts.
- La mateixa sol·licitud és la mateixa clau API, el mateix endpoint i els mateixos paràmetres de consulta. Una altra pàgina d’una llista és una altra sol·licitud i rep la seva pròpia resposta.
- Aniva només desa una resposta
200. Un error no es desa mai. - El temps comença quan Aniva desa la resposta. Una crida posterior no l’allarga.
- Quan la teva clau API crea, actualitza, activa o cancel·la alguna cosa, la següent lectura és nova. La següent lectura d’aquest registre amb una altra clau API teva també és nova.
- En una resposta d’enviament desada, els camps
synced_atiupdated_atpoden ser més antics que en una resposta nova. L’estat, el seguiment i les adreces estan actualitzats. - En una resposta de resultats desada, el nom d’un biomarcador, una unitat o un valor convertit poden tenir fins a 60 minuts d’antiguitat després que Aniva canviï el catàleg. Els valors mesurats estan actualitzats.
- Quan Aniva crea un esdeveniment de webhook per al teu webhook, la següent lectura d’aquest registre, dels seus resultats i de les seves llistes és nova. Així, la lectura que segueix un esdeveniment sempre mostra el canvi.
Capçaleres de resposta
Cada resposta d’aquests endpoints a una clau API vàlida inclou aquestes capçaleres:Bones pràctiques
- Descarta els duplicats. Omet qualsevol esdeveniment amb un
webhook-idque ja hagis processat. - Fes servir les revisions. Desa els valors més alts de
status_revision,results_revisionirevisionper objecte. Ignora qualsevol esdeveniment amb un valor inferior. - Consulta el
url. L’esdeveniment indica que alguna cosa ha canviat. L’endpointGETindica què. - Respon ràpidament. Posa l’esdeveniment en cua i respon amb
2xxabans de processar-lo. - Concilia les dades. Executa una tasca periòdica que llegeixi els objectes oberts amb els endpoints
GET. El sondeig continua sent una alternativa vàlida. Una lectura repetida pot rebre una resposta desada; consulta Lectures repetides. - Fes proves després de cada desplegament. Fes servir Envia un esdeveniment de prova.