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

> Rep una crida HTTPS d'Aniva quan canviï una cita, una comanda de kit de prova a casa, els seus resultats, un document pujat, una ubicació, un perfil o un enviament

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](https://docs.anivahealth.com/ca/api/webhooks/create-webhook.md).
   Desa el `secret` de la resposta. Aniva només el mostra una vegada.
3. [Verifica la signatura](#verifica-la-signatura) de cada petició.
4. Envia un [esdeveniment de prova](https://docs.anivahealth.com/ca/api/webhooks/send-test-event.md). Comprova el resultat a
   [Llistar lliuraments](https://docs.anivahealth.com/ca/api/webhooks/list-deliveries.md).

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.

| Tipus | Quan s'activa |
| - | - |
| `appointment.created` | La cita passa a ser visible per a tu. S'envia una vegada per cita. |
| `appointment.pending` | La cita passa a `pending`. |
| `appointment.confirmed` | La cita passa a `confirmed`. |
| `appointment.blood_drawn` | La cita passa a `blood_drawn`. |
| `appointment.cancelled` | La cita passa a `cancelled`. |
| `appointment.rescheduled` | Canvia `scheduled_at` o la ubicació. No s'envia quan la cita està en `cancelled`. |
| `appointment.results.updated` | Els resultats canvien. |
| `appointment.results.completed` | El `status` dels resultats passa a `completed`. |
| `appointment.results.fault` | El `status` dels resultats passa a `fault`. |
| `home_kit_order.created` | Es crea la comanda. S'envia una vegada per comanda. |
| `home_kit_order.pending` | La comanda passa a `pending`. |
| `home_kit_order.dispatched` | La comanda passa a `dispatched`. |
| `home_kit_order.activated` | La comanda passa a `activated`. |
| `home_kit_order.cancelled` | La comanda passa a `cancelled`. |
| `home_kit_order.results.updated` | Els resultats canvien. |
| `home_kit_order.results.completed` | El `status` dels resultats passa a `completed`. |
| `home_kit_order.results.fault` | El `status` dels resultats passa a `fault`. |
| `document.results.updated` | Els resultats d'un document que has pujat canvien, o el document s'emmagatzema. `stored` és final: no ve seguit de `document.results.completed`. |
| `document.results.completed` | El `status` dels resultats d'un document que has pujat passa a `completed`. |
| `document.results.fault` | El `status` dels resultats d'un document que has pujat passa a `fault`. |
| `document.deleted` | S'elimina un document que has pujat. S'envia als endpoints que van rebre el seu últim esdeveniment de resultats. Sense `url`. |
| `location.created` | La ubicació passa a ser visible per a tu: nova, activada o afegida a un grup que llegeixes. |
| `location.updated` | Canvia qualsevol camp de la ubicació: nom, adreça, lloc web, horari d'obertura, imatge. |
| `location.deactivated` | Ja no pots llegir la ubicació. |
| `location.retail_prices.updated` | Canvia un preu publicat de panell o biomarcador a la ubicació. Cal l'abast `retail_prices_view`. |
| `profile.created` | El perfil passa a ser visible per a tu: nou o afegit a un grup de perfils que llegeixes. |
| `profile.updated` | Canvia qualsevol camp d'[Obtén el perfil](https://docs.anivahealth.com/ca/api/profiles/get-profile.md). |
| `profile.deleted` | S'elimina el perfil o ja no el pots llegir. |
| `shipment.created` | L'enviament passa a ser visible per a tu. |
| `shipment.updated` | Canvia qualsevol camp de l'enviament: seguiment, escanejos, recollida, notes, enllaços. |
| `shipment.pending` | L'enviament passa a `pending`. |
| `shipment.in_transit` | L'enviament passa a `in_transit`. |
| `shipment.delivered` | L'enviament passa a `delivered`. |
| `shipment.fault` | L'enviament passa a `fault`. |
| `shipment.cancelled` | L'enviament passa a `cancelled`. |
| `ping` | Has enviat un esdeveniment de prova. S'envia sempre, no forma part d'`enabled_events`. |

* 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

| Camp | Descripció |
| - | - |
| `id` | ID de l'esdeveniment (UUID). Igual que la capçalera `webhook-id`. Es manté igual en reintents i reenviaments. |
| `type` | Tipus d'esdeveniment, per exemple `appointment.confirmed`. |
| `timestamp` | Quan s'ha produït el canvi, com a instant ISO 8601 en UTC. No és l'hora d'enviament. |
| `data` | L'objecte modificat. L'estructura depèn del tipus d'esdeveniment. |

### Dades dels esdeveniments d'estat

| Camp | Descripció |
| - | - |
| `object` | `appointment` o `home_kit_order`. |
| `id` | L'ID de la cita o de la comanda de kit de prova a casa (UUID). |
| `url` | `/api/v1/appointments/{id}` o `/api/v1/home-kit-orders/{id}`. |
| `status` | L'estat després del canvi. |
| `previous_status` | L'estat abans del canvi. `null` a `created`. |
| `status_revision` | Comptador per objecte. Augmenta amb cada canvi d'estat i pot saltar 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
  }
}
```

### Dades dels esdeveniments de resultats

| Camp | Descripció |
| - | - |
| `object` | `appointment`, `home_kit_order` o `document`. |
| `id` | L'ID de la cita, la comanda de kit de prova a casa o el document (UUID). |
| `url` | La ruta `/results` de l'objecte, p. ex. `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` o `fault`. Un document també pot estar en `stored`. |
| `previous_results_status` | El `results_status` de l'esdeveniment de resultats anterior. `null` en el primer. |
| `results_revision` | Comptador per objecte. Augmenta amb cada canvi de resultats i pot saltar 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
  }
}
```

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

```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
  }
}
```

### Dades dels esdeveniments d'ubicació, perfil i enviament

| Camp | Descripció |
| - | - |
| `object` | `location`, `profile` o `shipment`. |
| `id` | L'ID de la ubicació o del perfil (UUID), o la referència de l'enviament. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` o `/api/v1/shipments/{id}`. Absent a `.deactivated` i `.deleted`. |
| `status` | Només per a enviaments. L'estat després del canvi. |
| `previous_status` | Només per a enviaments. L'estat abans del canvi. `null` a `shipment.created`. |
| `revision` | Comptador per objecte per a tots els seus esdeveniments. Pot saltar números. Els esdeveniments de preus de venda tenen el seu propi comptador. |

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

```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)
    );
  });
}
```

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

| Intent | Temps després del primer intent |
| - | - |
| 2 | uns 5 segons |
| 3 | uns 5 minuts |
| 4 | uns 35 minuts |
| 5 | unes 2,5 hores |
| 6 | unes 7,5 hores |
| 7 | unes 17,5 hores |
| 8 | unes 27,5 hores |
| 9 | unes 51,5 hores |
| 10 | unes 75,5 hores |

Després de l'intent 10, el lliurament passa a `failed`. Torna'l a enviar amb
[Torna a enviar el lliurament](https://docs.anivahealth.com/ca/api/webhooks/resend-delivery.md). 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.

| `disabled_reason` | Causa |
| - | - |
| `Disabled by the partner` | Has enviat `status: "disabled"`. |
| `Disabled by Aniva` | Aniva ha desactivat el webhook. Només Aniva el pot reactivar. |
| `The endpoint answered 410 Gone` | El teu endpoint ha respost `410 Gone`. |
| `No successful delivery for 5 days` | No hi ha hagut cap lliurament reeixit durant 5 dies. |

Per tornar a començar, corregeix el teu endpoint i envia `status: "enabled"` amb
[Actualitza el webhook](https://docs.anivahealth.com/ca/api/webhooks/update-webhook.md). 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.

| Endpoint | Desada durant | Esdeveniments que t'avisen d'un canvi |
| - | - | - |
| [Obtén l'enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md) | 60 minuts | `shipment.created`, `shipment.updated` |
| [Llista els enviaments](https://docs.anivahealth.com/ca/api/shipments/list-shipments.md) | 5 minuts | `shipment.created`, `shipment.updated` |
| [Obtén la comanda del kit de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/get-home-kit.md) | 60 minuts | `home_kit_order.created` i un esdeveniment per estat, per exemple `home_kit_order.activated` |
| [Obtén els resultats de la comanda del kit de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/get-results.md) | 60 minuts | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Llista les comandes de kits de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/list-home-kits.md) | 5 minuts | els mateixos esdeveniments que per a una comanda de kit de prova a casa |
| [Obtén la cita](https://docs.anivahealth.com/ca/api/appointments/get-appointment.md) | 15 minuts | `appointment.created`, `appointment.rescheduled` i un esdeveniment per estat, per exemple `appointment.confirmed` |
| [Obtén els resultats de la cita](https://docs.anivahealth.com/ca/api/appointments/get-results.md) | 60 minuts | `appointment.results.updated`, `.completed`, `.fault` |
| [Llista les cites](https://docs.anivahealth.com/ca/api/appointments/list-appointments.md) | 5 minuts | els mateixos esdeveniments que per a una cita |
| [Llista els perfils](https://docs.anivahealth.com/ca/api/profiles/list-profiles.md) | 5 minuts | `profile.created`, `profile.updated`, `profile.deleted` |

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

| Capçalera | S'envia amb | Significat |
| - | - | - |
| `Aniva-Webhook-Events` | Cada resposta | Els esdeveniments de webhook que cobreixen l'endpoint, separats per comes. |
| `Link` | Cada resposta | L'adreça d'aquesta pàgina, amb `rel="help"`. |
| `Cache-Status` | Una resposta `200` | `Aniva; hit; ttl=3476` és una resposta desada. `ttl` és el nombre de segons fins que hi hagi disponible una resposta nova. `Aniva; fwd=miss; stored; ttl=3600` és una resposta nova que Aniva ha desat ara. `Aniva; fwd=miss` és una resposta nova que Aniva no ha desat. |
| `Age` | Una resposta desada | L'antiguitat de la resposta desada en segons. |
| `Cache-Control` | Una resposta `200` | `private, no-cache`. No desis la resposta en una memòria cau pròpia en lloc de fer una crida 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"
```

## 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](#lectures-repetides).
* **Fes proves després de cada desplegament.** Fes servir [Envia un esdeveniment de prova](https://docs.anivahealth.com/ca/api/webhooks/send-test-event.md).


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