Passer au contenu principal
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. Conserve le secret de la réponse. Aniva ne l’affiche qu’une seule fois.
  3. Vérifie la signature de chaque requête.
  4. Envoie un événement de test. Vérifie le résultat dans Lister les livraisons.
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.
  • 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

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
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.
Node.js
Le schéma est Standard Webhooks. 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 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 : 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 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. 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 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.
  • 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 :

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.
  • Teste après chaque déploiement. Utilise Envoyer un événement de test.