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

> Reçois un appel HTTPS d'Aniva lorsqu'un rendez-vous, une commande de kit à domicile, ses résultats, un document importé, un lieu, un profil ou une expédition change

Un webhook est une requête HTTPS `POST` qu'Aniva envoie à ton serveur quand quelque chose change. Tu n'as
pas besoin de faire du polling.

Les événements sont légers. Ils contiennent l'identifiant de l'objet, le nouveau statut, une révision et l'`url` à lire. Ils
ne contiennent jamais de valeurs de laboratoire ni de données personnelles. Lis l'`url` avec ta clé API pour récupérer les données.

## Configuration rapide

1. Mets en place un endpoint HTTPS qui accepte `POST` et répond `2xx` en moins de 15 secondes.
2. Enregistre-le avec [Créer un webhook](https://docs.anivahealth.com/fr/api/webhooks/create-webhook.md).
   Conserve le `secret` de la réponse. Aniva ne l'affiche qu'une seule fois.
3. [Vérifie la signature](#verifier-la-signature) de chaque requête.
4. Envoie un [événement de test](https://docs.anivahealth.com/fr/api/webhooks/send-test-event.md). Vérifie le résultat dans
   [Lister les livraisons](https://docs.anivahealth.com/fr/api/webhooks/list-deliveries.md).

Ta clé API a besoin du scope `webhooks_manage`. Demande à Aniva de l'ajouter. Un webhook appartient à la
clé API qui l'a créé, et une clé peut détenir au maximum 5 webhooks.

## Événements

Tu reçois un événement uniquement pour les objets que ta clé API peut lire avec l'endpoint `GET` correspondant.
Choisis les types avec `enabled_events`. Envoie `["*"]` pour recevoir tous les types, y compris les types ajoutés par la suite.

| Type | Quand il se déclenche |
| - | - |
| `appointment.created` | Le rendez-vous devient visible pour toi. Envoyé une fois par rendez-vous. |
| `appointment.pending` | Le rendez-vous passe à `pending`. |
| `appointment.confirmed` | Le rendez-vous passe à `confirmed`. |
| `appointment.blood_drawn` | Le rendez-vous passe à `blood_drawn`. |
| `appointment.cancelled` | Le rendez-vous passe à `cancelled`. |
| `appointment.rescheduled` | `scheduled_at` ou le lieu change. Non envoyé quand le rendez-vous est `cancelled`. |
| `appointment.results.updated` | Les résultats changent. |
| `appointment.results.completed` | Le `status` des résultats passe à `completed`. |
| `appointment.results.fault` | Le `status` des résultats passe à `fault`. |
| `home_kit_order.created` | La commande est créée. Envoyé une fois par commande. |
| `home_kit_order.pending` | La commande passe à `pending`. |
| `home_kit_order.dispatched` | La commande passe à `dispatched`. |
| `home_kit_order.activated` | La commande passe à `activated`. |
| `home_kit_order.cancelled` | La commande passe à `cancelled`. |
| `home_kit_order.results.updated` | Les résultats changent. |
| `home_kit_order.results.completed` | Le `status` des résultats passe à `completed`. |
| `home_kit_order.results.fault` | Le `status` des résultats passe à `fault`. |
| `document.results.updated` | Les résultats d'un document que tu as importé changent, ou il est stocké. `stored` est final : aucun `document.results.completed` ne suit. |
| `document.results.completed` | Le `status` des résultats d'un document que tu as importé passe à `completed`. |
| `document.results.fault` | Le `status` des résultats d'un document que tu as importé passe à `fault`. |
| `document.deleted` | Un document que tu as importé est supprimé. Envoyé aux endpoints qui ont reçu son dernier événement de résultats. Pas d'`url`. |
| `location.created` | Le lieu devient visible pour toi : nouveau, activé ou ajouté à un groupe que tu lis. |
| `location.updated` | Un champ du lieu change : nom, adresse, site web, horaires d'ouverture, image. |
| `location.deactivated` | Tu ne peux plus lire le lieu. |
| `location.retail_prices.updated` | Un prix publié de panel ou de biomarqueur du lieu change. Nécessite le scope `retail_prices_view`. |
| `profile.created` | Le profil devient visible pour toi : nouveau ou ajouté à un groupe de profils que tu lis. |
| `profile.updated` | Un champ de [Récupérer un profil](https://docs.anivahealth.com/fr/api/profiles/get-profile.md) change. |
| `profile.deleted` | Le profil est supprimé, ou tu ne peux plus le lire. |
| `shipment.created` | L'expédition devient visible pour toi. |
| `shipment.updated` | Un champ de l'expédition change : suivi, scans, enlèvement, notes, liens. |
| `shipment.pending` | L'expédition passe à `pending`. |
| `shipment.in_transit` | L'expédition passe à `in_transit`. |
| `shipment.delivered` | L'expédition passe à `delivered`. |
| `shipment.fault` | L'expédition passe à `fault`. |
| `shipment.cancelled` | L'expédition passe à `cancelled`. |
| `ping` | Tu as envoyé un événement de test. Toujours envoyé, ne fait pas partie de `enabled_events`. |

* Un événement de statut se déclenche à chaque passage dans ce statut, y compris lors d'un retour en arrière. Par exemple, un kit qui repasse de `dispatched` à `pending` envoie `home_kit_order.pending`.
* Un seul changement peut envoyer deux événements avec le même `status_revision`, par exemple `appointment.confirmed` et `appointment.rescheduled`.
* `results.updated` se déclenche à chaque changement des résultats : une nouvelle valeur, une correction, une erreur, un nouveau document ou un document remplacé, ou un échantillon qui quitte l'objet. Il arrive quelques minutes après le dernier changement.
* `results.completed` et `results.fault` s'accompagnent toujours d'un `results.updated` avec le même `results_revision`. Les résultats peuvent se rouvrir puis se terminer à nouveau, tu peux donc recevoir un deuxième `results.completed`.

Abonne-toi à `results.updated` pour afficher des résultats partiels, ou à `results.completed` pour agir uniquement sur les résultats finaux.

`results.completed` suit les valeurs des résultats, pas le PDF. Le PDF du rapport peut arriver avant ou après les valeurs. Certains laboratoires envoient d'abord un PDF préliminaire, puis le remplacent par le PDF final sous le même `id` de document. Le remplacement envoie `results.updated`. Lis `documents[].original_file_name` pour distinguer les deux : Labor Quade termine un rapport préliminaire (Vorbefund) par `_V` et le rapport final (Endbefund) par `_E`, par exemple `7642100312_B0012_FA_E.pdf`.

Les événements de lieu, de profil et d'expédition arrivent en quelques minutes. Aniva attend que l'objet n'ait pas changé pendant 2 minutes, afin qu'une série de modifications n'envoie qu'un seul événement. Ces règles s'appliquent aussi :

* Les profils anonymes n'envoient aucun événement.
* Une expédition n'envoie aucun événement quand tu y perds accès.
* Un changement de statut d'expédition envoie `shipment.updated` et l'événement `shipment.<status>` avec la même `revision`.

## Charge utile

| Champ | Description |
| - | - |
| `id` | ID de l'événement (UUID). Égal à l'en-tête `webhook-id`. Reste identique en cas de nouvelle tentative ou de renvoi. |
| `type` | Type d'événement, par exemple `appointment.confirmed`. |
| `timestamp` | Moment du changement, au format ISO 8601 UTC. Pas l'heure d'envoi. |
| `data` | L'objet modifié. La structure dépend du type d'événement. |

### Données des événements de statut

| Champ | Description |
| - | - |
| `object` | `appointment` ou `home_kit_order`. |
| `id` | L'ID du rendez-vous ou de la commande de kit à domicile (UUID). |
| `url` | `/api/v1/appointments/{id}` ou `/api/v1/home-kit-orders/{id}`. |
| `status` | Le statut après le changement. |
| `previous_status` | Le statut avant le changement. `null` pour `created`. |
| `status_revision` | Compteur par objet. Il augmente à chaque changement de statut et peut sauter des numéros. |

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

### Données des événements de résultats

| Champ | Description |
| - | - |
| `object` | `appointment`, `home_kit_order` ou `document`. |
| `id` | L'ID du rendez-vous, de la commande de kit à domicile ou du document (UUID). |
| `url` | La route `/results` de l'objet, par ex. `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` ou `fault`. Un document peut aussi être `stored`. |
| `previous_results_status` | Le `results_status` de l'événement de résultats précédent. `null` pour le premier. |
| `results_revision` | Compteur par objet. Il augmente à chaque changement de résultats et peut sauter des numéros. |

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

### Données de l'événement de suppression de document

`document.deleted` contient `object` (`document`), `id`, `previous_results_status` et `results_revision`. Il n'a pas d'`url`, car il ne reste rien à lire.

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

### Données des événements de lieu, de profil et d'expédition

| Champ | Description |
| - | - |
| `object` | `location`, `profile` ou `shipment`. |
| `id` | L'ID du lieu ou du profil (UUID), ou la référence de l'expédition. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` ou `/api/v1/shipments/{id}`. Absent pour `.deactivated` et `.deleted`. |
| `status` | Expéditions uniquement. Le statut après le changement. |
| `previous_status` | Expéditions uniquement. Le statut avant le changement. `null` pour `shipment.created`. |
| `revision` | Compteur par objet pour l'ensemble de ses événements. Il peut sauter des numéros. Les événements de prix publics ont leur propre compteur. |

```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` contient `data.object` `webhook` et `data.id`, l'ID du webhook.

## Vérifier la signature

Les événements ne contiennent pas de données, mais tu devrais tout de même vérifier chacun d'eux. Une signature valide prouve que l'événement vient d'Aniva. Chaque requête comporte les en-têtes `webhook-id`, `webhook-timestamp` (secondes Unix) et `webhook-signature`.

1. Prends le corps brut de la requête. Vérifie-le avant d'analyser le JSON.
2. Construis le contenu signé `{webhook-id}.{webhook-timestamp}.{raw body}`.
3. Décode en base64 la partie de ton secret située après `whsec_`. Utilise-la comme clé.
4. Calcule le HMAC-SHA256 du contenu signé et encode-le en base64.
5. Compare-le en temps constant avec chaque entrée `v1,<signature>` de `webhook-signature`. Les entrées sont séparées par des espaces. Une seule correspondance suffit.
6. Rejette la requête quand `webhook-timestamp` s'écarte de plus de 5 minutes de ton horloge.

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

Le schéma est [Standard Webhooks](https://www.standardwebhooks.com). Des bibliothèques Standard Webhooks existent pour la plupart des langages et font cela en un seul appel.

### Renouveler le secret

Appelle [Renouveler le secret](https://docs.anivahealth.com/fr/api/webhooks/rotate-secret.md) pour obtenir un nouveau secret. Pendant 24 heures, Aniva
signe avec l'ancien et le nouveau secret, donc déploie le nouveau dans ce délai. Après une fuite, envoie
`revoke_current_secret_now: true` pour désactiver l'ancien secret immédiatement.

## Livraison

* Réponds `2xx` en moins de 15 secondes. Enregistre ou mets l'événement en file d'attente et traite-le plus tard.
* Utilise une URL `https` sur le port 443 avec un hôte public. Aniva ne suit pas les redirections : un `3xx`
  compte comme un échec.
* La livraison se fait au moins une fois et sans ordre garanti. Élimine les doublons avec `webhook-id`. Utilise les révisions pour
  ignorer un événement plus ancien.
* Réponds `410 Gone` pour arrêter les événements. Aniva désactive le webhook immédiatement.
* Aniva conserve les livraisons pendant 30 jours. Passé ce délai, tu ne peux plus les lister ni les renvoyer.

### Nouvelles tentatives

Une réponse autre que `2xx`, un délai d'attente dépassé ou une erreur réseau déclenche une nouvelle tentative. Chaque événement a jusqu'à 10 tentatives
sur environ trois jours :

| Tentative | Délai après la première tentative |
| - | - |
| 2 | environ 5 secondes |
| 3 | environ 5 minutes |
| 4 | environ 35 minutes |
| 5 | environ 2,5 heures |
| 6 | environ 7,5 heures |
| 7 | environ 17,5 heures |
| 8 | environ 27,5 heures |
| 9 | environ 51,5 heures |
| 10 | environ 75,5 heures |

Après la tentative 10, la livraison passe à `failed`. Renvoie-la avec
[Renvoyer la livraison](https://docs.anivahealth.com/fr/api/webhooks/resend-delivery.md). Elle conserve le même `webhook-id`.

### Notifications d'échec

Aniva envoie un e-mail aux adresses `alert_emails` du webhook lorsqu'aucune livraison n'a réussi pendant 24 heures, lorsqu'un événement passe à
`failed` et lorsque le webhook est désactivé. Après 5 jours sans livraison réussie, Aniva
désactive le webhook. Un webhook désactivé ne reçoit plus de nouveaux événements et ses livraisons en attente sont
annulées.

| `disabled_reason` | Cause |
| - | - |
| `Disabled by the partner` | Tu as envoyé `status: "disabled"`. |
| `Disabled by Aniva` | Aniva a désactivé le webhook. Seule Aniva peut le réactiver. |
| `The endpoint answered 410 Gone` | Ton endpoint a répondu `410 Gone`. |
| `No successful delivery for 5 days` | Aucune livraison n'a réussi pendant 5 jours. |

Pour reprendre, corrige ton endpoint et envoie `status: "enabled"` avec
[Mettre à jour le webhook](https://docs.anivahealth.com/fr/api/webhooks/update-webhook.md). Les événements manqués ne sont pas renvoyés
automatiquement. Renvoie-les ou lis l'état actuel avec les endpoints `GET`.

## Lectures répétées

Aniva conserve la réponse de certains endpoints `GET` pendant un court instant. Lorsque ta clé API envoie de nouveau la même
requête dans ce délai, tu reçois la réponse conservée. Tu n'obtiens aucune erreur et le corps a le
même format.

* **Un enregistrement** (une expédition, une commande de kit à domicile, un rendez-vous et les résultats des deux derniers) :
  à chaque appel, Aniva vérifie que l'enregistrement n'a pas changé. S'il a changé, tu reçois une nouvelle réponse.
* **Une liste** peut être plus ancienne que ses enregistrements, de 5 minutes au maximum.

Pour connaître un changement immédiatement, utilise les événements de webhook du tableau.

| Endpoint | Conservée pendant | Événements signalant un changement |
| - | - | - |
| [Obtenir une expédition](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md) | 60 minutes | `shipment.created`, `shipment.updated` |
| [Lister les expéditions](https://docs.anivahealth.com/fr/api/shipments/list-shipments.md) | 5 minutes | `shipment.created`, `shipment.updated` |
| [Obtenir une commande de kit à domicile](https://docs.anivahealth.com/fr/api/home-kit-orders/get-home-kit.md) | 60 minutes | `home_kit_order.created` et un événement par statut, par exemple `home_kit_order.activated` |
| [Obtenir les résultats d'une commande de kit à domicile](https://docs.anivahealth.com/fr/api/home-kit-orders/get-results.md) | 60 minutes | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Lister les commandes de kit à domicile](https://docs.anivahealth.com/fr/api/home-kit-orders/list-home-kits.md) | 5 minutes | les mêmes événements que pour une commande de kit à domicile |
| [Obtenir un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/get-appointment.md) | 15 minutes | `appointment.created`, `appointment.rescheduled` et un événement par statut, par exemple `appointment.confirmed` |
| [Obtenir les résultats d'un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/get-results.md) | 60 minutes | `appointment.results.updated`, `.completed`, `.fault` |
| [Lister les rendez-vous](https://docs.anivahealth.com/fr/api/appointments/list-appointments.md) | 5 minutes | les mêmes événements que pour un rendez-vous |
| [Lister les profils](https://docs.anivahealth.com/fr/api/profiles/list-profiles.md) | 5 minutes | `profile.created`, `profile.updated`, `profile.deleted` |

* Une même requête correspond à la même clé API, au même endpoint et aux mêmes paramètres de requête. Une autre
  page d'une liste est une autre requête et reçoit sa propre réponse.
* Aniva ne conserve que les réponses `200`. Une erreur n'est jamais conservée.
* Le délai commence lorsqu'Aniva conserve la réponse. Un appel ultérieur ne le prolonge pas.
* Une fois que ta clé API crée, met à jour, active ou annule quelque chose, ta lecture suivante est à jour.
  La lecture suivante de cet enregistrement avec une autre de tes clés API est également à jour.
* Dans une réponse d'expédition conservée, les champs `synced_at` et `updated_at` peuvent être plus anciens que dans une
  nouvelle réponse. Le statut, le suivi et les adresses sont à jour.
* Dans une réponse de résultats conservée, un nom de biomarqueur, une unité ou une valeur convertie peut dater de 60
  minutes au maximum après une modification du catalogue par Aniva. Les valeurs mesurées sont à jour.
* Une fois qu'Aniva crée un événement de webhook pour ton webhook, ta lecture suivante de cet enregistrement, de ses
  résultats et de ses listes est à jour. Ainsi, la lecture qui suit un événement reflète toujours le changement.

### En-têtes de réponse

Chaque réponse de ces endpoints à une clé API valide comporte ces en-têtes :

| En-tête | Envoyé avec | Signification |
| - | - | - |
| `Aniva-Webhook-Events` | Chaque réponse | Les événements de webhook qui couvrent l'endpoint, séparés par des virgules. |
| `Link` | Chaque réponse | L'adresse de cette page, avec `rel="help"`. |
| `Cache-Status` | Une réponse `200` | `Aniva; hit; ttl=3476` est une réponse conservée. `ttl` est le nombre de secondes avant qu'une nouvelle réponse soit disponible. `Aniva; fwd=miss; stored; ttl=3600` est une nouvelle réponse qu'Aniva vient de conserver. `Aniva; fwd=miss` est une nouvelle réponse qu'Aniva n'a pas conservée. |
| `Age` | Une réponse conservée | L'âge de la réponse conservée en secondes. |
| `Cache-Control` | Une réponse `200` | `private, no-cache`. Ne garde pas la réponse dans ton propre cache à la place d'un appel à 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"
```

## Bonnes pratiques

* **Élimine les doublons.** Ignore un événement dont tu as déjà traité le `webhook-id`.
* **Utilise les révisions.** Enregistre les valeurs les plus élevées de `status_revision`, `results_revision` et `revision`
  par objet. Ignore tout événement dont la valeur est inférieure.
* **Récupère l'`url`.** L'événement indique que quelque chose a changé. L'endpoint `GET` indique quoi.
* **Réponds vite.** Mets l'événement en file d'attente et réponds `2xx` avant de le traiter.
* **Rapproche les données.** Lance une tâche régulière qui lit les objets ouverts avec les endpoints `GET`. Le polling reste une
  solution de secours valable. Une lecture répétée peut renvoyer une réponse conservée, voir [Lectures répétées](#lectures-repetees).
* **Teste après chaque déploiement.** Utilise [Envoyer un événement de test](https://docs.anivahealth.com/fr/api/webhooks/send-test-event.md).


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