> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Recibe una llamada HTTPS de Aniva cuando cambie una cita, un pedido de kit de prueba en casa, sus resultados, un documento subido, una ubicación, un perfil o un envío

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](https://docs.anivahealth.com/es/api/webhooks/create-webhook.md).
   Guarda el `secret` de la respuesta. Aniva solo lo muestra una vez.
3. [Verifica la firma](#verificar-la-firma) de cada petición.
4. Envía un [evento de prueba](https://docs.anivahealth.com/es/api/webhooks/send-test-event.md). Comprueba el resultado en
   [Listar entregas](https://docs.anivahealth.com/es/api/webhooks/list-deliveries.md).

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.

| Tipo | Cuándo se dispara |
| - | - |
| `appointment.created` | La cita pasa a ser visible para ti. Se envía una vez por cita. |
| `appointment.pending` | La cita pasa a `pending`. |
| `appointment.confirmed` | La cita pasa a `confirmed`. |
| `appointment.blood_drawn` | La cita pasa a `blood_drawn`. |
| `appointment.cancelled` | La cita pasa a `cancelled`. |
| `appointment.rescheduled` | Cambia `scheduled_at` o la ubicación. No se envía cuando la cita está en `cancelled`. |
| `appointment.results.updated` | Los resultados cambian. |
| `appointment.results.completed` | El `status` de los resultados pasa a `completed`. |
| `appointment.results.fault` | El `status` de los resultados pasa a `fault`. |
| `home_kit_order.created` | Se crea el pedido. Se envía una vez por pedido. |
| `home_kit_order.pending` | El pedido pasa a `pending`. |
| `home_kit_order.dispatched` | El pedido pasa a `dispatched`. |
| `home_kit_order.activated` | El pedido pasa a `activated`. |
| `home_kit_order.cancelled` | El pedido pasa a `cancelled`. |
| `home_kit_order.results.updated` | Los resultados cambian. |
| `home_kit_order.results.completed` | El `status` de los resultados pasa a `completed`. |
| `home_kit_order.results.fault` | El `status` de los resultados pasa a `fault`. |
| `document.results.updated` | Cambian los resultados de un documento que has subido o se almacena. `stored` es final: no le sigue ningún `document.results.completed`. |
| `document.results.completed` | El `status` de los resultados de un documento que has subido pasa a `completed`. |
| `document.results.fault` | El `status` de los resultados de un documento que has subido pasa a `fault`. |
| `document.deleted` | Se elimina un documento que has subido. Se envía a los endpoints que recibieron su último evento de resultados. Sin `url`. |
| `location.created` | La ubicación pasa a ser visible para ti: nueva, activada o añadida a un grupo que puedes leer. |
| `location.updated` | Cambia cualquier campo de la ubicación: nombre, dirección, sitio web, horario de apertura, imagen. |
| `location.deactivated` | Ya no puedes leer la ubicación. |
| `location.retail_prices.updated` | Cambia el precio publicado de un panel o biomarcador en la ubicación. Requiere el scope `retail_prices_view`. |
| `profile.created` | El perfil pasa a ser visible para ti: nuevo o añadido a un grupo de perfiles que puedes leer. |
| `profile.updated` | Cambia cualquier campo de [Obtener perfil](https://docs.anivahealth.com/es/api/profiles/get-profile.md). |
| `profile.deleted` | Se elimina el perfil o ya no puedes leerlo. |
| `shipment.created` | El envío pasa a ser visible para ti. |
| `shipment.updated` | Cambia cualquier campo del envío: seguimiento, escaneos, recogida, notas, enlaces. |
| `shipment.pending` | El envío pasa a `pending`. |
| `shipment.in_transit` | El envío pasa a `in_transit`. |
| `shipment.delivered` | El envío pasa a `delivered`. |
| `shipment.fault` | El envío pasa a `fault`. |
| `shipment.cancelled` | El envío pasa a `cancelled`. |
| `ping` | Has enviado un evento de prueba. Se envía siempre, no forma parte de `enabled_events`. |

* 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

| Campo | Descripción |
| - | - |
| `id` | ID del evento (UUID). Igual que la cabecera `webhook-id`. Se mantiene igual en reintentos y reenvíos. |
| `type` | Tipo de evento, por ejemplo, `appointment.confirmed`. |
| `timestamp` | Cuándo ocurrió el cambio, como instante ISO 8601 UTC. No es la hora del envío. |
| `data` | El objeto modificado. La estructura depende del tipo de evento. |

### Datos de eventos de estado

| Campo | Descripción |
| - | - |
| `object` | `appointment` o `home_kit_order`. |
| `id` | ID de la cita o del pedido de kit de prueba en casa (UUID). |
| `url` | `/api/v1/appointments/{id}` o `/api/v1/home-kit-orders/{id}`. |
| `status` | El estado después del cambio. |
| `previous_status` | El estado antes del cambio. `null` en `created`. |
| `status_revision` | Contador por objeto. Aumenta con cada cambio de estado y puede saltarse números. |

```json appointment.confirmed theme={null}
{
  "id": "0b8e6f3a-2c4d-4e7f-9a1b-3c5d7e9f1a2b",
  "type": "appointment.confirmed",
  "timestamp": "2026-10-15T09:12:44.512Z",
  "data": {
    "object": "appointment",
    "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "url": "https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "status": "confirmed",
    "previous_status": "pending",
    "status_revision": 2
  }
}
```

### Datos de eventos de resultados

| Campo | Descripción |
| - | - |
| `object` | `appointment`, `home_kit_order` o `document`. |
| `id` | ID de la cita, del pedido de kit de prueba en casa o del documento (UUID). |
| `url` | La ruta `/results` del objeto, p. ej., `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` o `fault`. Un documento también puede estar en `stored`. |
| `previous_results_status` | El `results_status` del evento de resultados anterior. `null` en el primero. |
| `results_revision` | Contador por objeto. Aumenta con cada cambio en los resultados y puede saltarse números. |

```json home_kit_order.results.completed theme={null}
{
  "id": "6d2a9c4e-8f1b-4a3d-b5e7-0c2f4a6b8d1e",
  "type": "home_kit_order.results.completed",
  "timestamp": "2026-10-15T14:03:00.000Z",
  "data": {
    "object": "home_kit_order",
    "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "url": "https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/results",
    "results_status": "completed",
    "previous_results_status": "in_progress",
    "results_revision": 4
  }
}
```

### 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.

```json document.deleted theme={null}
{
  "id": "1c9e7a52-3f4b-4d8a-9e61-7b2c5d0f8a14",
  "type": "document.deleted",
  "timestamp": "2026-10-24T09:12:00.000Z",
  "data": {
    "object": "document",
    "id": "f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c",
    "previous_results_status": "completed",
    "results_revision": 3
  }
}
```

### Datos de eventos de ubicación, perfil y envío

| Campo | Descripción |
| - | - |
| `object` | `location`, `profile` o `shipment`. |
| `id` | ID de la ubicación o del perfil (UUID), o la referencia del envío. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` o `/api/v1/shipments/{id}`. Ausente en `.deactivated` y `.deleted`. |
| `status` | Solo envíos. El estado después del cambio. |
| `previous_status` | Solo envíos. El estado antes del cambio. `null` en `shipment.created`. |
| `revision` | Contador por objeto en todos sus eventos. Puede saltarse números. Los eventos de precios de venta al público tienen su propio contador. |

```json shipment.in_transit theme={null}
{
  "id": "3f7c1a2b-9d4e-4b6a-8c5f-2e1d0a9b8c7d",
  "type": "shipment.in_transit",
  "timestamp": "2026-10-16T08:41:12.000Z",
  "data": {
    "object": "shipment",
    "id": "P2610164821",
    "url": "https://anivahealth.com/api/v1/shipments/P2610164821",
    "status": "in_transit",
    "previous_status": "pending",
    "revision": 3
  }
}
```

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.

```typescript Node.js theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyAnivaWebhook(rawBody: string, headers: Headers, secret: string): boolean {
  const id = headers.get('webhook-id') ?? '';
  const timestamp = headers.get('webhook-timestamp') ?? '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();

  return (headers.get('webhook-signature') ?? '').split(' ').some((entry) => {
    const [version, signature = ''] = entry.split(',');
    const received = Buffer.from(signature, 'base64');
    return (
      version === 'v1' && received.length === expected.length && timingSafeEqual(received, expected)
    );
  });
}
```

El esquema es [Standard Webhooks](https://www.standardwebhooks.com). 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](https://docs.anivahealth.com/es/api/webhooks/rotate-secret.md) 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:

| Intento | Tiempo tras el primer intento |
| - | - |
| 2 | unos 5 segundos |
| 3 | unos 5 minutos |
| 4 | unos 35 minutos |
| 5 | unas 2,5 horas |
| 6 | unas 7,5 horas |
| 7 | unas 17,5 horas |
| 8 | unas 27,5 horas |
| 9 | unas 51,5 horas |
| 10 | unas 75,5 horas |

Tras el intento 10, la entrega pasa a `failed`. Vuelve a enviarla con
[Reenviar entrega](https://docs.anivahealth.com/es/api/webhooks/resend-delivery.md). 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.

| `disabled_reason` | Causa |
| - | - |
| `Disabled by the partner` | Enviaste `status: "disabled"`. |
| `Disabled by Aniva` | Aniva desactivó el webhook. Solo Aniva puede reactivarlo. |
| `The endpoint answered 410 Gone` | Tu endpoint respondió `410 Gone`. |
| `No successful delivery for 5 days` | Ninguna entrega tuvo éxito durante 5 días. |

Para reanudar, corrige tu endpoint y envía `status: "enabled"` con
[Actualizar webhook](https://docs.anivahealth.com/es/api/webhooks/update-webhook.md). 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.

| Endpoint | Guardado durante | Eventos que avisan de un cambio |
| - | - | - |
| [Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md) | 60 minutos | `shipment.created`, `shipment.updated` |
| [Listar envíos](https://docs.anivahealth.com/es/api/shipments/list-shipments.md) | 5 minutos | `shipment.created`, `shipment.updated` |
| [Obtener pedido de kit de prueba en casa](https://docs.anivahealth.com/es/api/home-kit-orders/get-home-kit.md) | 60 minutos | `home_kit_order.created` y un evento por estado, por ejemplo `home_kit_order.activated` |
| [Obtener resultados de pedido de kit de prueba en casa](https://docs.anivahealth.com/es/api/home-kit-orders/get-results.md) | 60 minutos | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Listar pedidos de kit de prueba en casa](https://docs.anivahealth.com/es/api/home-kit-orders/list-home-kits.md) | 5 minutos | los mismos eventos que para un pedido de kit de prueba en casa |
| [Obtener cita](https://docs.anivahealth.com/es/api/appointments/get-appointment.md) | 15 minutos | `appointment.created`, `appointment.rescheduled` y un evento por estado, por ejemplo `appointment.confirmed` |
| [Obtener resultados de cita](https://docs.anivahealth.com/es/api/appointments/get-results.md) | 60 minutos | `appointment.results.updated`, `.completed`, `.fault` |
| [Listar citas](https://docs.anivahealth.com/es/api/appointments/list-appointments.md) | 5 minutos | los mismos eventos que para una cita |
| [Listar perfiles](https://docs.anivahealth.com/es/api/profiles/list-profiles.md) | 5 minutos | `profile.created`, `profile.updated`, `profile.deleted` |

* 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:

| Cabecera | Se envía con | Significado |
| - | - | - |
| `Aniva-Webhook-Events` | Cada respuesta | Los eventos de webhook que cubren el endpoint, separados por comas. |
| `Link` | Cada respuesta | La dirección de esta página, con `rel="help"`. |
| `Cache-Status` | Una respuesta `200` | `Aniva; hit; ttl=3476` es una respuesta guardada. `ttl` es el número de segundos hasta que haya una respuesta nueva disponible. `Aniva; fwd=miss; stored; ttl=3600` es una respuesta nueva que Aniva acaba de guardar. `Aniva; fwd=miss` es una respuesta nueva que Aniva no ha guardado. |
| `Age` | Una respuesta guardada | La antigüedad de la respuesta guardada en segundos. |
| `Cache-Control` | Una respuesta `200` | `private, no-cache`. No guardes la respuesta en una caché propia en lugar de llamar a Aniva. |

```http theme={null}
HTTP/1.1 200 OK
Age: 124
Cache-Status: Aniva; hit; ttl=3476
Cache-Control: private, no-cache
Aniva-Webhook-Events: shipment.created, shipment.updated
Link: <https://docs.anivahealth.com/concepts/webhooks>; rel="help"
```

## 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](#lecturas-repetidas).
* **Prueba tras cada despliegue.** Usa [Enviar evento de prueba](https://docs.anivahealth.com/es/api/webhooks/send-test-event.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.