Saltar al contingut principal
Un webhook és una petició HTTPS 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

  1. Crea un punt final HTTPS que accepti POST i respongui 2xx en un màxim de 15 segons.
  2. Registra’l amb Crear un webhook. Desa el secret de la resposta. Aniva només el mostra una vegada.
  3. Verifica la signatura de cada petició.
  4. Envia un esdeveniment de prova. Comprova el resultat a Llistar lliuraments.
La teva clau d’API necessita l’abast 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’endpoint GET 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 dispatched a pending envia home_kit_order.pending.
  • Un sol canvi pot enviar dos esdeveniments amb la mateixa status_revision, per exemple appointment.confirmed i appointment.rescheduled.
  • results.updated s’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.completed i results.fault sempre arriben amb un results.updated de la mateixa results_revision. Els resultats es poden reobrir i tornar a completar, així que pots rebre un segon results.completed.
Subscriu-te a 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.updated i l’esdeveniment shipment.<status> amb la mateixa revision.

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
Un 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çaleres webhook-id, webhook-timestamp (segons Unix) i webhook-signature.
  1. Agafa el cos en brut de la petició. Verifica’l abans d’analitzar el JSON.
  2. Construeix el contingut signat {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Descodifica en base64 la part del teu secret després de whsec_. Fes-la servir com a clau.
  4. Calcula l’HMAC-SHA256 del contingut signat i codifica’l en base64.
  5. Compara’l en temps constant amb cada entrada v1,<signature> de webhook-signature. Les entrades estan separades per espais. Amb una coincidència n’hi ha prou.
  6. Rebutja la petició quan webhook-timestamp difereixi en més de 5 minuts del teu rellotge.
Node.js
L’esquema és Standard Webhooks. Hi ha biblioteques de Standard Webhooks per a la majoria de llenguatges que ho fan en una sola crida.

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ó, envia revoke_current_secret_now: true per aturar el secret antic a l’instant.

Lliurament

  • Respon amb 2xx en 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 https al port 443 amb un amfitrió públic. Aniva no segueix les redireccions: un 3xx compta 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 Gone per 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 de 2xx, 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 als alert_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 endpoints GET 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.
Per conèixer un canvi a l’instant, fes servir els esdeveniments de webhook de la taula.
  • 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_at i updated_at poden 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-id que ja hagis processat.
  • Fes servir les revisions. Desa els valors més alts de status_revision, results_revision i revision per objecte. Ignora qualsevol esdeveniment amb un valor inferior.
  • Consulta el url. L’esdeveniment indica que alguna cosa ha canviat. L’endpoint GET indica què.
  • Respon ràpidament. Posa l’esdeveniment en cua i respon amb 2xx abans 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.