Saltar al contenido principal
Un webhook es una petición HTTPS 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

  1. Crea un endpoint HTTPS que acepte POST y responda 2xx en menos de 15 segundos.
  2. Regístralo con Crear webhook. Guarda el secret de la respuesta. Aniva solo lo muestra una vez.
  3. Verifica la firma de cada petición.
  4. Envía un evento de prueba. Comprueba el resultado en Listar entregas.
Tu clave de API necesita el scope 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 endpoint GET 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 dispatched a pending envía home_kit_order.pending.
  • Un solo cambio puede enviar dos eventos con el mismo status_revision, por ejemplo, appointment.confirmed y appointment.rescheduled.
  • results.updated se 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.completed y results.fault siempre van acompañados de un results.updated con el mismo results_revision. Los resultados pueden reabrirse y volver a completarse, así que puedes recibir un segundo results.completed.
Suscríbete a 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.updated y el evento shipment.<status> con el mismo revision.

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
Un 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 cabeceras webhook-id, webhook-timestamp (segundos Unix) y webhook-signature.
  1. Toma el cuerpo sin procesar de la petición. Verifícalo antes de analizar el JSON.
  2. Construye el contenido firmado {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Decodifica en base64 la parte de tu secreto posterior a whsec_. Úsala como clave.
  4. Calcula el HMAC-SHA256 del contenido firmado y codifícalo en base64.
  5. Compáralo en tiempo constante con cada entrada v1,<signature> de webhook-signature. Las entradas están separadas por espacios. Basta con una coincidencia.
  6. Rechaza la petición cuando webhook-timestamp difiera en más de 5 minutos de tu reloj.
Node.js
El esquema es Standard Webhooks. Existen librerías de Standard Webhooks para la mayoría de los lenguajes y hacen esto en una sola llamada.

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ía revoke_current_secret_now: true para desactivar el secreto antiguo al instante.

Entrega

  • Responde 2xx en un máximo de 15 segundos. Guarda el evento o ponlo en cola y procésalo después.
  • Usa una URL https en el puerto 443 con un host público. Aniva no sigue redirecciones: un 3xx cuenta 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 Gone para 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 de 2xx, 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 a alert_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 endpoints GET 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.
Para enterarte de un cambio al instante, usa los eventos de webhook de la tabla.
  • 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_at y updated_at pueden 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-id ya hayas procesado.
  • Usa las revisiones. Guarda el valor más alto de status_revision, results_revision y revision por objeto. Ignora cualquier evento con un valor inferior.
  • Consulta la url. El evento indica que algo ha cambiado. El endpoint GET dice qué.
  • Responde rápido. Pon el evento en cola y responde 2xx antes 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.