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
- Mets en place un endpoint HTTPS qui accepte
POSTet répond2xxen moins de 15 secondes. - Enregistre-le avec Créer un webhook.
Conserve le
secretde la réponse. Aniva ne l’affiche qu’une seule fois. - Vérifie la signature de chaque requête.
- Envoie un événement de test. Vérifie le résultat dans Lister les livraisons.
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’endpointGET correspondant.
Choisis les types avec enabled_events. Envoie ["*"] pour recevoir tous les types, y compris les types ajoutés par la suite.
- 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àpendingenvoiehome_kit_order.pending. - Un seul changement peut envoyer deux événements avec le même
status_revision, par exempleappointment.confirmedetappointment.rescheduled. results.updatedse 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.completedetresults.faults’accompagnent toujours d’unresults.updatedavec le mêmeresults_revision. Les résultats peuvent se rouvrir puis se terminer à nouveau, tu peux donc recevoir un deuxièmeresults.completed.
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.updatedet l’événementshipment.<status>avec la mêmerevision.
Charge utile
Données des événements de statut
appointment.confirmed
Données des événements de résultats
home_kit_order.results.completed
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.
document.deleted
Données des événements de lieu, de profil et d’expédition
shipment.in_transit
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êteswebhook-id, webhook-timestamp (secondes Unix) et webhook-signature.
- Prends le corps brut de la requête. Vérifie-le avant d’analyser le JSON.
- Construis le contenu signé
{webhook-id}.{webhook-timestamp}.{raw body}. - Décode en base64 la partie de ton secret située après
whsec_. Utilise-la comme clé. - Calcule le HMAC-SHA256 du contenu signé et encode-le en base64.
- Compare-le en temps constant avec chaque entrée
v1,<signature>dewebhook-signature. Les entrées sont séparées par des espaces. Une seule correspondance suffit. - Rejette la requête quand
webhook-timestamps’écarte de plus de 5 minutes de ton horloge.
Node.js
Renouveler le secret
Appelle Renouveler le secret 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, envoierevoke_current_secret_now: true pour désactiver l’ancien secret immédiatement.
Livraison
- Réponds
2xxen moins de 15 secondes. Enregistre ou mets l’événement en file d’attente et traite-le plus tard. - Utilise une URL
httpssur le port 443 avec un hôte public. Aniva ne suit pas les redirections : un3xxcompte 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 Gonepour 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 que2xx, 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 :
Après la tentative 10, la livraison passe à
failed. Renvoie-la avec
Renvoyer la livraison. Elle conserve le même webhook-id.
Notifications d’échec
Aniva envoie un e-mail aux adressesalert_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.
Pour reprendre, corrige ton endpoint et envoie
status: "enabled" avec
Mettre à jour le webhook. 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 endpointsGET 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.
- 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_atetupdated_atpeuvent ê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 :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_revisionetrevisionpar 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’endpointGETindique quoi. - Réponds vite. Mets l’événement en file d’attente et réponds
2xxavant 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. - Teste après chaque déploiement. Utilise Envoyer un événement de test.