POST que Aniva envía a tu servidor cuando algo cambia. No
necesitas hacer consultas periódicas.
Los eventos son ligeros. Contienen el ID del objeto, el nuevo estado, una revisión y la url para leer. Nunca
contienen valores de laboratorio ni datos personales. Lee la url con tu clave de API para obtener los datos.
Configuración rápida
- Crea un endpoint HTTPS que acepte
POSTy responda2xxen menos de 15 segundos. - Regístralo con Crear webhook.
Guarda el
secretde la respuesta. Aniva solo lo muestra una vez. - Verifica la firma de cada petición.
- Envía un evento de prueba. Comprueba el resultado en Listar entregas.
webhooks_manage. Pide a Aniva que lo añada. Un webhook pertenece a la
clave de API que lo creó y una clave puede tener como máximo 5 webhooks.
Eventos
Solo recibes un evento para los objetos que tu clave de API puede leer con el endpointGET correspondiente.
Elige los tipos con enabled_events. Envía ["*"] para recibir todos los tipos, incluidos los que se añadan más adelante.
- Un evento de estado se dispara con cada paso a ese estado, también al volver atrás. Por ejemplo, un kit que
vuelve de
dispatchedapendingenvíahome_kit_order.pending. - Un solo cambio puede enviar dos eventos con el mismo
status_revision, por ejemplo,appointment.confirmedyappointment.rescheduled. results.updatedse dispara con cada cambio en los resultados: un valor nuevo, una corrección, un fallo, un documento nuevo o sustituido, o una muestra que sale del objeto. Llega pocos minutos después del último cambio.results.completedyresults.faultsiempre van acompañados de unresults.updatedcon el mismoresults_revision. Los resultados pueden reabrirse y volver a completarse, así que puedes recibir un segundoresults.completed.
results.updated para mostrar resultados parciales, o a results.completed para actuar solo con
los resultados finales.
results.completed sigue los valores de los resultados, no el PDF. El PDF del informe puede llegar antes o
después de los valores. Algunos laboratorios envían primero un PDF preliminar y después lo sustituyen por el final
con el mismo id de documento. La sustitución envía results.updated. Lee
documents[].original_file_name para distinguirlos: Labor Quade termina un informe preliminar
(Vorbefund) en _V y el informe final (Endbefund) en _E, por ejemplo,
7642100312_B0012_FA_E.pdf.
Los eventos de ubicación, perfil y envío llegan en pocos minutos. Aniva espera a que el objeto lleve
2 minutos sin cambiar, así que una ráfaga de ediciones envía un solo evento. También se aplican estas reglas:
- Los perfiles anónimos no envían eventos.
- Un envío no dispara ningún evento cuando pierdes acceso a él.
- Un cambio de estado en un envío dispara
shipment.updatedy el eventoshipment.<status>con el mismorevision.
Payload
Datos de eventos de estado
appointment.confirmed
Datos de eventos de resultados
home_kit_order.results.completed
Datos del evento de documento eliminado
document.deleted incluye object (document), id, previous_results_status y
results_revision. No tiene url, porque ya no queda nada que leer.
document.deleted
Datos de eventos de ubicación, perfil y envío
shipment.in_transit
ping incluye data.object webhook y data.id, el ID del webhook.
Verificar la firma
Los eventos no llevan datos, pero aun así deberías verificar cada uno. Una firma válida demuestra que el evento viene de Aniva. Cada petición incluye las cabeceraswebhook-id, webhook-timestamp (segundos
Unix) y webhook-signature.
- Toma el cuerpo sin procesar de la petición. Verifícalo antes de analizar el JSON.
- Construye el contenido firmado
{webhook-id}.{webhook-timestamp}.{raw body}. - Decodifica en base64 la parte de tu secreto posterior a
whsec_. Úsala como clave. - Calcula el HMAC-SHA256 del contenido firmado y codifícalo en base64.
- Compáralo en tiempo constante con cada entrada
v1,<signature>dewebhook-signature. Las entradas están separadas por espacios. Basta con una coincidencia. - Rechaza la petición cuando
webhook-timestampdifiera en más de 5 minutos de tu reloj.
Node.js
Rotar el secreto
Llama a Rotar secreto para obtener un secreto nuevo. Durante 24 horas, Aniva firma con el secreto antiguo y el nuevo, así que despliega el nuevo en ese plazo. Tras una filtración, envíarevoke_current_secret_now: true para desactivar el secreto antiguo al instante.
Entrega
- Responde
2xxen un máximo de 15 segundos. Guarda el evento o ponlo en cola y procésalo después. - Usa una URL
httpsen el puerto 443 con un host público. Aniva no sigue redirecciones: un3xxcuenta como fallo. - La entrega es al menos una vez y sin orden. Descarta duplicados por
webhook-id. Usa las revisiones para ignorar eventos más antiguos. - Responde
410 Gonepara detener los eventos. Aniva desactiva el webhook al instante. - Aniva guarda las entregas durante 30 días. Pasado ese plazo, no puedes listarlas ni reenviarlas.
Reintentos
Una respuesta distinta de2xx, un tiempo de espera agotado o un error de red inicia un reintento. Cada evento tiene hasta 10 intentos
a lo largo de unos tres días:
Tras el intento 10, la entrega pasa a
failed. Vuelve a enviarla con
Reenviar entrega. Conserva el mismo webhook-id.
Avisos de fallo
Aniva envía un correo aalert_emails del webhook cuando no hay ninguna entrega correcta durante 24 horas, cuando un evento pasa a
failed y cuando se desactiva el webhook. Tras 5 días sin ninguna entrega correcta, Aniva
desactiva el webhook. Un webhook desactivado no recibe eventos nuevos y sus entregas pendientes se
cancelan.
Para reanudar, corrige tu endpoint y envía
status: "enabled" con
Actualizar webhook. Los eventos perdidos no se vuelven a enviar
automáticamente. Reenvíalos o consulta el estado actual con los endpoints GET.
Lecturas repetidas
Aniva guarda la respuesta de algunos endpointsGET durante un tiempo breve. Cuando tu clave API vuelve a enviar la misma
solicitud dentro de ese plazo, recibes la respuesta guardada. No recibes ningún error y el cuerpo tiene el
mismo formato.
- Un registro (un envío, un pedido de kit de prueba en casa, una cita y los resultados de los dos últimos): en cada llamada, Aniva comprueba que el registro no haya cambiado. Si ha cambiado, recibes una respuesta nueva.
- Una lista puede ser más antigua que sus registros, 5 minutos como máximo.
- La misma solicitud implica la misma clave API, el mismo endpoint y los mismos parámetros de consulta. Otra página de una lista es otra solicitud y recibe su propia respuesta.
- Aniva solo guarda una respuesta
200. Nunca se guarda un error. - El plazo empieza cuando Aniva guarda la respuesta. Una llamada posterior no lo alarga.
- Después de que tu clave API cree, actualice, active o cancele algo, tu siguiente lectura es nueva. La siguiente lectura de ese registro con otra de tus claves API también es nueva.
- En una respuesta de envío guardada, los campos
synced_atyupdated_atpueden ser más antiguos que en una respuesta nueva. El estado, el seguimiento y las direcciones están al día. - En una respuesta de resultados guardada, el nombre de un biomarcador, una unidad o un valor convertido pueden tener hasta 60 minutos de antigüedad después de que Aniva cambie su catálogo. Los valores medidos están al día.
- Después de que Aniva cree un evento de webhook para tu webhook, tu siguiente lectura de ese registro, de sus resultados y de sus listas es nueva. Así, la lectura que sigue a un evento siempre muestra el cambio.
Cabeceras de respuesta
Cada respuesta de estos endpoints a una clave API válida incluye estas cabeceras:Buenas prácticas
- Descarta duplicados. Omite cualquier evento cuyo
webhook-idya hayas procesado. - Usa las revisiones. Guarda el valor más alto de
status_revision,results_revisionyrevisionpor objeto. Ignora cualquier evento con un valor inferior. - Consulta la
url. El evento indica que algo ha cambiado. El endpointGETdice qué. - Responde rápido. Pon el evento en cola y responde
2xxantes de procesarlo. - Concilia los datos. Ejecuta una tarea periódica que lea los objetos abiertos con los endpoints
GET. El polling sigue siendo una alternativa válida. Una lectura repetida puede devolver una respuesta guardada; consulta Lecturas repetidas. - Prueba tras cada despliegue. Usa Enviar evento de prueba.