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

# Webhook

> Ricevi una chiamata HTTPS da Aniva quando un appuntamento, un ordine di kit domiciliare, i suoi risultati, un documento caricato, una sede, un profilo o una spedizione cambiano

Un webhook è una richiesta HTTPS `POST` che Aniva invia al tuo server quando cambia qualcosa. Non devi
effettuare il polling.

Gli eventi sono leggeri. Contengono l'ID dell'oggetto, il nuovo stato, una revisione e l'`url` da leggere. Non
contengono mai valori di laboratorio o dati personali. Leggi l'`url` con la tua chiave API per ottenere i dati.

## Configurazione rapida

1. Crea un endpoint HTTPS che accetti `POST` e risponda `2xx` entro 15 secondi.
2. Registralo con [Crea webhook](https://docs.anivahealth.com/it/api/webhooks/create-webhook.md).
   Salva il `secret` dalla risposta. Aniva lo mostra una sola volta.
3. [Verifica la firma](#verifica-la-firma) di ogni richiesta.
4. Invia un [evento di test](https://docs.anivahealth.com/it/api/webhooks/send-test-event.md). Controlla il risultato in
   [Elenca consegne](https://docs.anivahealth.com/it/api/webhooks/list-deliveries.md).

La tua chiave API richiede lo scope `webhooks_manage`. Chiedi ad Aniva di aggiungerlo. Un webhook appartiene alla
chiave API che lo ha creato e una chiave può avere al massimo 5 webhook.

## Eventi

Ricevi un evento solo per gli oggetti che la tua chiave API può leggere con l'endpoint `GET` corrispondente.
Scegli i tipi con `enabled_events`. Invia `["*"]` per ricevere tutti i tipi, anche quelli aggiunti in seguito.

| Tipo | Quando si attiva |
| - | - |
| `appointment.created` | L'appuntamento diventa visibile per te. Inviato una volta per appuntamento. |
| `appointment.pending` | L'appuntamento passa a `pending`. |
| `appointment.confirmed` | L'appuntamento passa a `confirmed`. |
| `appointment.blood_drawn` | L'appuntamento passa a `blood_drawn`. |
| `appointment.cancelled` | L'appuntamento passa a `cancelled`. |
| `appointment.rescheduled` | Cambia `scheduled_at` o la sede. Non viene inviato quando l'appuntamento è `cancelled`. |
| `appointment.results.updated` | I risultati cambiano. |
| `appointment.results.completed` | Lo `status` dei risultati passa a `completed`. |
| `appointment.results.fault` | Lo `status` dei risultati passa a `fault`. |
| `home_kit_order.created` | L'ordine viene creato. Inviato una volta per ordine. |
| `home_kit_order.pending` | L'ordine passa a `pending`. |
| `home_kit_order.dispatched` | L'ordine passa a `dispatched`. |
| `home_kit_order.activated` | L'ordine passa a `activated`. |
| `home_kit_order.cancelled` | L'ordine passa a `cancelled`. |
| `home_kit_order.results.updated` | I risultati cambiano. |
| `home_kit_order.results.completed` | Lo `status` dei risultati passa a `completed`. |
| `home_kit_order.results.fault` | Lo `status` dei risultati passa a `fault`. |
| `document.results.updated` | I risultati di un documento che hai caricato cambiano, oppure viene archiviato. `stored` è finale: non segue alcun `document.results.completed`. |
| `document.results.completed` | Lo `status` dei risultati di un documento che hai caricato passa a `completed`. |
| `document.results.fault` | Lo `status` dei risultati di un documento che hai caricato passa a `fault`. |
| `document.deleted` | Un documento che hai caricato viene eliminato. Inviato agli endpoint che hanno ricevuto il suo ultimo evento sui risultati. Nessun `url`. |
| `location.created` | La sede diventa visibile per te: nuova, attivata o aggiunta a un gruppo che leggi. |
| `location.updated` | Cambia qualsiasi campo della sede: nome, indirizzo, sito web, orari di apertura, immagine. |
| `location.deactivated` | Non puoi più leggere la sede. |
| `location.retail_prices.updated` | Cambia il prezzo pubblicato di un pannello o di un biomarcatore presso la sede. Richiede lo scope `retail_prices_view`. |
| `profile.created` | Il profilo diventa visibile per te: nuovo o aggiunto a un gruppo di profili che leggi. |
| `profile.updated` | Cambia qualsiasi campo di [Ottieni profilo](https://docs.anivahealth.com/it/api/profiles/get-profile.md). |
| `profile.deleted` | Il profilo viene eliminato o non puoi più leggerlo. |
| `shipment.created` | La spedizione diventa visibile per te. |
| `shipment.updated` | Cambia qualsiasi campo della spedizione: tracking, scansioni, ritiro, note, link. |
| `shipment.pending` | La spedizione passa a `pending`. |
| `shipment.in_transit` | La spedizione passa a `in_transit`. |
| `shipment.delivered` | La spedizione passa a `delivered`. |
| `shipment.fault` | La spedizione passa a `fault`. |
| `shipment.cancelled` | La spedizione passa a `cancelled`. |
| `ping` | Hai inviato un evento di test. Inviato sempre, non fa parte di `enabled_events`. |

* Un evento di stato si attiva a ogni passaggio a quello stato, anche tornando indietro. Per esempio,
  un kit che torna da `dispatched` a `pending` invia `home_kit_order.pending`.
* Una singola modifica può inviare due eventi con la stessa `status_revision`, per esempio
  `appointment.confirmed` e `appointment.rescheduled`.
* `results.updated` si attiva a ogni modifica dei risultati: un nuovo valore, una correzione, un
  errore, un documento nuovo o sostituito, o un campione che lascia l'oggetto. Arriva entro pochi
  minuti dall'ultima modifica.
* `results.completed` e `results.fault` arrivano sempre insieme a un `results.updated` con la stessa
  `results_revision`. I risultati possono riaprirsi e completarsi di nuovo, quindi puoi ricevere un
  secondo `results.completed`.

Iscriviti a `results.updated` per mostrare risultati parziali, oppure a `results.completed` per
agire solo sui risultati finali.

`results.completed` segue i valori dei risultati, non il PDF. Il PDF del referto può arrivare prima
o dopo i valori. Alcuni laboratori inviano prima un PDF preliminare e poi lo sostituiscono con
quello definitivo mantenendo lo stesso `id` del documento. La sostituzione invia `results.updated`.
Leggi `documents[].original_file_name` per distinguerli: Labor Quade termina il referto preliminare
(Vorbefund) con `_V` e il referto definitivo (Endbefund) con `_E`, per esempio
`7642100312_B0012_FA_E.pdf`.

Gli eventi di sedi, profili e spedizioni arrivano entro pochi minuti. Aniva aspetta che l'oggetto
non cambi per 2 minuti, così più modifiche ravvicinate inviano un solo evento. Valgono anche queste
regole:

* I profili anonimi non inviano eventi.
* Una spedizione non invia eventi quando perdi l'accesso.
* Un cambio di stato di una spedizione invia `shipment.updated` e l'evento `shipment.<status>` con
  la stessa `revision`.

## Payload

| Campo | Descrizione |
| - | - |
| `id` | ID dell'evento (UUID). Uguale all'header `webhook-id`. Resta uguale nei tentativi successivi e nei reinvii. |
| `type` | Tipo di evento, per esempio `appointment.confirmed`. |
| `timestamp` | Quando è avvenuta la modifica, come istante ISO 8601 UTC. Non l'orario di invio. |
| `data` | L'oggetto modificato. La struttura dipende dal tipo di evento. |

### Dati degli eventi di stato

| Campo | Descrizione |
| - | - |
| `object` | `appointment` o `home_kit_order`. |
| `id` | L'ID dell'appuntamento o dell'ordine del kit domiciliare (UUID). |
| `url` | `/api/v1/appointments/{id}` o `/api/v1/home-kit-orders/{id}`. |
| `status` | Lo stato dopo la modifica. |
| `previous_status` | Lo stato prima della modifica. `null` su `created`. |
| `status_revision` | Contatore per oggetto. Aumenta a ogni cambio di stato e può saltare dei numeri. |

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

### Dati degli eventi sui risultati

| Campo | Descrizione |
| - | - |
| `object` | `appointment`, `home_kit_order` o `document`. |
| `id` | L'ID dell'appuntamento, dell'ordine del kit domiciliare o del documento (UUID). |
| `url` | Il percorso `/results` dell'oggetto, per es. `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` o `fault`. Un documento può anche essere `stored`. |
| `previous_results_status` | Il `results_status` dell'evento sui risultati precedente. `null` al primo evento. |
| `results_revision` | Contatore per oggetto. Aumenta a ogni modifica dei risultati e può saltare dei numeri. |

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

### Dati dell'evento di eliminazione documento

`document.deleted` contiene `object` (`document`), `id`, `previous_results_status` e
`results_revision`. Non ha `url`, perché non rimane nulla da leggere.

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

### Dati degli eventi di sedi, profili e spedizioni

| Campo | Descrizione |
| - | - |
| `object` | `location`, `profile` o `shipment`. |
| `id` | L'ID della sede o del profilo (UUID), oppure il riferimento della spedizione. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` o `/api/v1/shipments/{id}`. Assente su `.deactivated` e `.deleted`. |
| `status` | Solo spedizioni. Lo stato dopo la modifica. |
| `previous_status` | Solo spedizioni. Lo stato prima della modifica. `null` su `shipment.created`. |
| `revision` | Contatore per oggetto su tutti i suoi eventi. Può saltare dei numeri. Gli eventi sui prezzi al pubblico hanno un proprio contatore. |

```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` contiene `data.object` `webhook` e `data.id`, l'ID del webhook.

## Verifica la firma

Gli eventi non contengono dati, ma dovresti comunque verificarli tutti. Una firma valida dimostra
che l'evento proviene da Aniva. Ogni richiesta include gli header `webhook-id`, `webhook-timestamp`
(secondi Unix) e `webhook-signature`.

1. Prendi il corpo grezzo della richiesta. Verificalo prima di fare il parsing del JSON.
2. Costruisci il contenuto firmato `{webhook-id}.{webhook-timestamp}.{raw body}`.
3. Decodifica in base64 la parte del tuo segreto dopo `whsec_`. Usala come chiave.
4. Calcola l'HMAC-SHA256 del contenuto firmato e codificalo in base64.
5. Confrontalo in tempo costante con ogni voce `v1,<signature>` in `webhook-signature`. Le voci sono
   separate da spazi. Basta una corrispondenza.
6. Rifiuta la richiesta quando `webhook-timestamp` differisce di più di 5 minuti dal tuo orologio.

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

Lo schema è [Standard Webhooks](https://www.standardwebhooks.com). Esistono librerie Standard
Webhooks per la maggior parte dei linguaggi che eseguono questa verifica in una sola chiamata.

### Ruota il segreto

Chiama [Ruota segreto](https://docs.anivahealth.com/it/api/webhooks/rotate-secret.md) per ottenere un nuovo segreto. Per 24 ore Aniva
firma con il vecchio e il nuovo segreto, quindi distribuisci il nuovo entro quel tempo. Se il
segreto viene compromesso, invia `revoke_current_secret_now: true` per disattivare subito quello
vecchio.

## Consegna

* Rispondi con `2xx` entro 15 secondi. Salva o metti in coda l'evento ed elaboralo in seguito.
* Usa un URL `https` sulla porta 443 con un host pubblico. Aniva non segue i reindirizzamenti: un
  `3xx` conta come fallimento.
* La consegna è almeno una volta e non ordinata. Scarta i duplicati tramite `webhook-id`. Usa le
  revisioni per ignorare un evento più vecchio.
* Rispondi con `410 Gone` per interrompere gli eventi. Aniva disattiva subito il webhook.
* Aniva conserva le consegne per 30 giorni. Dopo quel periodo, non puoi elencarle né reinviarle.

### Nuovi tentativi

Una risposta diversa da `2xx`, un timeout o un errore di rete avvia un nuovo tentativo. Ogni evento
ha fino a 10 tentativi nell'arco di circa tre giorni:

| Tentativo | Tempo dopo il primo tentativo |
| - | - |
| 2 | circa 5 secondi |
| 3 | circa 5 minuti |
| 4 | circa 35 minuti |
| 5 | circa 2,5 ore |
| 6 | circa 7,5 ore |
| 7 | circa 17,5 ore |
| 8 | circa 27,5 ore |
| 9 | circa 51,5 ore |
| 10 | circa 75,5 ore |

Dopo il tentativo 10, la consegna è `failed`. Inviala di nuovo con
[Reinvia consegna](https://docs.anivahealth.com/it/api/webhooks/resend-delivery.md). Mantiene lo stesso `webhook-id`.

### Avvisi di errore

Aniva invia un'email agli indirizzi in `alert_emails` del webhook quando nessuna consegna va a buon
fine per 24 ore, quando un evento è `failed` e quando il webhook viene disattivato. Dopo 5 giorni
senza consegne riuscite, Aniva disattiva il webhook. Un webhook disattivato non riceve nuovi eventi
e le sue consegne in attesa vengono annullate.

| `disabled_reason` | Causa |
| - | - |
| `Disabled by the partner` | Hai inviato `status: "disabled"`. |
| `Disabled by Aniva` | Aniva ha disattivato il webhook. Solo Aniva può riattivarlo. |
| `The endpoint answered 410 Gone` | Il tuo endpoint ha risposto `410 Gone`. |
| `No successful delivery for 5 days` | Nessuna consegna è riuscita per 5 giorni. |

Per ricominciare, correggi il tuo endpoint e invia `status: "enabled"` con
[Aggiorna webhook](https://docs.anivahealth.com/it/api/webhooks/update-webhook.md). Gli eventi persi non vengono
reinviati automaticamente. Reinviali, oppure leggi lo stato attuale con gli endpoint `GET`.

## Letture ripetute

Aniva memorizza la risposta di alcuni endpoint `GET` per un breve periodo. Quando la tua chiave API
invia di nuovo la stessa richiesta entro questo intervallo, ricevi la risposta memorizzata. Non
ricevi alcun errore e il corpo ha lo stesso formato.

* **Un singolo record** (una spedizione, un ordine di kit domiciliare, un appuntamento e i risultati
  degli ultimi due): a ogni chiamata, Aniva verifica che il record non sia cambiato. Se è cambiato,
  ricevi una risposta aggiornata.
* **Un elenco** può essere meno recente dei suoi record, al massimo di 5 minuti.

Per sapere subito di una modifica, usa gli eventi webhook nella tabella.

| Endpoint | Memorizzato per | Eventi che segnalano una modifica |
| - | - | - |
| [Ottieni spedizione](https://docs.anivahealth.com/it/api/shipments/get-shipment.md) | 60 minuti | `shipment.created`, `shipment.updated` |
| [Elenca spedizioni](https://docs.anivahealth.com/it/api/shipments/list-shipments.md) | 5 minuti | `shipment.created`, `shipment.updated` |
| [Ottieni ordine kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/get-home-kit.md) | 60 minuti | `home_kit_order.created` e un evento per stato, per esempio `home_kit_order.activated` |
| [Ottieni risultati ordine kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/get-results.md) | 60 minuti | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Elenca ordini kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/list-home-kits.md) | 5 minuti | gli stessi eventi di un singolo ordine di kit domiciliare |
| [Ottieni appuntamento](https://docs.anivahealth.com/it/api/appointments/get-appointment.md) | 15 minuti | `appointment.created`, `appointment.rescheduled` e un evento per stato, per esempio `appointment.confirmed` |
| [Ottieni risultati appuntamento](https://docs.anivahealth.com/it/api/appointments/get-results.md) | 60 minuti | `appointment.results.updated`, `.completed`, `.fault` |
| [Elenca appuntamenti](https://docs.anivahealth.com/it/api/appointments/list-appointments.md) | 5 minuti | gli stessi eventi di un singolo appuntamento |
| [Elenca profili](https://docs.anivahealth.com/it/api/profiles/list-profiles.md) | 5 minuti | `profile.created`, `profile.updated`, `profile.deleted` |

* Per stessa richiesta si intende la stessa chiave API, lo stesso endpoint e gli stessi parametri
  di query. Un'altra pagina di un elenco è un'altra richiesta e riceve la propria risposta.
* Aniva memorizza solo una risposta `200`. Un errore non viene mai memorizzato.
* Il tempo inizia quando Aniva memorizza la risposta. Una chiamata successiva non lo prolunga.
* Dopo che la tua chiave API crea, aggiorna, attiva o annulla qualcosa, la tua lettura successiva
  è aggiornata. Anche la lettura successiva di quel record con un'altra tua chiave API è
  aggiornata.
* In una risposta memorizzata di una spedizione, i campi `synced_at` e `updated_at` possono
  essere meno recenti rispetto a una risposta aggiornata. Stato, tracciamento e indirizzi sono
  attuali.
* In una risposta memorizzata dei risultati, il nome di un biomarcatore, un'unità o un valore
  convertito possono risalire fino a 60 minuti prima dopo una modifica al catalogo di Aniva. I
  valori misurati sono attuali.
* Dopo che Aniva crea un evento webhook per il tuo webhook, la tua lettura successiva di quel
  record, dei suoi risultati e dei suoi elenchi è aggiornata. Così la lettura che segue un evento
  mostra sempre la modifica.

### Header di risposta

Ogni risposta di questi endpoint a una chiave API valida contiene questi header:

| Header | Inviato con | Significato |
| - | - | - |
| `Aniva-Webhook-Events` | Ogni risposta | Gli eventi webhook che coprono l'endpoint, separati da virgole. |
| `Link` | Ogni risposta | L'indirizzo di questa pagina, con `rel="help"`. |
| `Cache-Status` | Una risposta `200` | `Aniva; hit; ttl=3476` è una risposta memorizzata. `ttl` è il numero di secondi prima che sia disponibile una risposta aggiornata. `Aniva; fwd=miss; stored; ttl=3600` è una risposta aggiornata che Aniva ha appena memorizzato. `Aniva; fwd=miss` è una risposta aggiornata che Aniva non ha memorizzato. |
| `Age` | Una risposta memorizzata | L'età della risposta memorizzata in secondi. |
| `Cache-Control` | Una risposta `200` | `private, no-cache`. Non conservare la risposta in una tua cache al posto di una chiamata ad 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"
```

## Buone pratiche

* **Scarta i duplicati.** Salta un evento con un `webhook-id` che hai già elaborato.
* **Usa le revisioni.** Salva il valore più alto di `status_revision`, `results_revision` e
  `revision` per oggetto. Ignora un evento con un valore inferiore.
* **Recupera l'`url`.** L'evento dice che qualcosa è cambiato. L'endpoint `GET` dice cosa.
* **Rispondi in fretta.** Metti in coda l'evento e rispondi con `2xx` prima di elaborarlo.
* **Riconcilia.** Esegui un job periodico che legge gli oggetti aperti con gli endpoint `GET`. Il
  polling resta un valido fallback. Una lettura ripetuta può ricevere una risposta memorizzata,
  vedi [Letture ripetute](#letture-ripetute).
* **Fai un test dopo ogni deploy.** Usa [Invia evento di test](https://docs.anivahealth.com/it/api/webhooks/send-test-event.md).


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