Zum Hauptinhalt springen
Ein Webhook ist ein HTTPS-POST, den Aniva an deinen Server sendet, wenn sich etwas ändert. Du musst nicht regelmäßig abfragen. Ereignisse sind schlank. Sie enthalten die Objekt-ID, den neuen Status, eine Revision und die url zum Abrufen. Sie enthalten niemals Laborwerte oder personenbezogene Daten. Rufe die url mit deinem API-Schlüssel ab, um die Daten zu erhalten.

Schnelleinrichtung

  1. Erstelle einen HTTPS-Endpunkt, der POST akzeptiert und innerhalb von 15 Sekunden mit 2xx antwortet.
  2. Registriere ihn über Webhook erstellen. Speichere das secret aus der Antwort. Aniva zeigt es nur einmal an.
  3. Prüfe die Signatur jeder Anfrage.
  4. Sende ein Testereignis. Prüfe das Ergebnis unter Zustellungen auflisten.
Dein API-Schlüssel benötigt den Scope webhooks_manage. Bitte Aniva, ihn hinzuzufügen. Ein Webhook gehört zu dem API-Schlüssel, der ihn erstellt hat, und ein Schlüssel kann höchstens 5 Webhooks besitzen.

Events

Du erhältst ein Event nur für Objekte, die dein API-Key mit dem passenden GET-Endpunkt lesen kann. Wähle die Typen über enabled_events. Sende ["*"], um jeden Typ zu erhalten, auch später hinzugefügte Typen.
  • Ein Status-Event wird bei jedem Wechsel in diesen Status ausgelöst, auch bei einem Wechsel zurück. Zum Beispiel sendet ein Kit, das von dispatched zurück in pending wechselt, home_kit_order.pending.
  • Eine Änderung kann zwei Events mit derselben status_revision senden, zum Beispiel appointment.confirmed und appointment.rescheduled.
  • results.updated wird bei jeder Änderung der Ergebnisse ausgelöst: ein neuer Wert, eine Korrektur, ein Fehler, ein neues oder ersetztes Dokument oder eine Probe, die das Objekt verlässt. Es trifft innerhalb weniger Minuten nach der letzten Änderung ein.
  • results.completed und results.fault kommen immer zusammen mit einem results.updated derselben results_revision. Ergebnisse können wieder geöffnet und erneut abgeschlossen werden, sodass du ein zweites results.completed erhalten kannst.
Abonniere results.updated, um Teilergebnisse anzuzeigen, oder results.completed, um nur bei endgültigen Ergebnissen zu reagieren. results.completed richtet sich nach den Ergebniswerten, nicht nach dem PDF. Das Berichts-PDF kann vor oder nach den Werten eintreffen. Manche Labore senden zuerst ein vorläufiges PDF und ersetzen es später unter derselben Dokument-id durch das endgültige. Das Ersetzen sendet results.updated. Lies documents[].original_file_name, um die beiden zu unterscheiden: Bei Labor Quade endet ein vorläufiger Bericht (Vorbefund) auf _V und der endgültige Bericht (Endbefund) auf _E, zum Beispiel 7642100312_B0012_FA_E.pdf. Standort-, Profil- und Sendungs-Events treffen innerhalb weniger Minuten ein. Aniva wartet, bis sich das Objekt 2 Minuten lang nicht geändert hat, sodass mehrere schnelle Änderungen ein Event senden. Außerdem gelten diese Regeln:
  • Anonyme Profile senden keine Events.
  • Eine Sendung sendet kein Event, wenn du den Zugriff darauf verlierst.
  • Eine Statusänderung einer Sendung sendet shipment.updated und das shipment.<status>-Event mit derselben revision.

Payload

Daten von Status-Events

appointment.confirmed

Daten von Ergebnis-Events

home_kit_order.results.completed

Daten von Events zu gelöschten Dokumenten

document.deleted enthält object (document), id, previous_results_status und results_revision. Es hat keine url, da nichts mehr zu lesen ist.
document.deleted

Daten von Standort-, Profil- und Sendungs-Events

shipment.in_transit
Ein ping enthält data.object webhook und data.id, die Webhook-ID.

Signatur prüfen

Events enthalten keine Daten, aber du solltest trotzdem jedes einzelne prüfen. Eine gültige Signatur beweist, dass das Event von Aniva stammt. Jede Anfrage enthält die Header webhook-id, webhook-timestamp (Unix-Sekunden) und webhook-signature.
  1. Nimm den unverarbeiteten Request-Body. Prüfe ihn, bevor du das JSON parst.
  2. Erstelle den signierten Inhalt {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Dekodiere den Teil deines Secrets nach whsec_ per Base64. Verwende ihn als Schlüssel.
  4. Berechne den HMAC-SHA256 des signierten Inhalts und kodiere ihn als Base64.
  5. Vergleiche ihn in konstanter Zeit mit jedem v1,<signature>-Eintrag in webhook-signature. Die Einträge sind durch Leerzeichen getrennt. Eine Übereinstimmung genügt.
  6. Lehne die Anfrage ab, wenn webhook-timestamp mehr als 5 Minuten von deiner Uhr abweicht.
Node.js
Das Schema ist Standard Webhooks. Für die meisten Sprachen gibt es Bibliotheken für Standard Webhooks, die das in einem Aufruf erledigen.

Secret rotieren

Rufe Secret rotieren auf, um ein neues Secret zu erhalten. 24 Stunden lang signiert Aniva mit dem alten und dem neuen Secret, deploye das neue also innerhalb dieser Zeit. Nach einem Leak sendest du revoke_current_secret_now: true, um das alte Secret sofort zu deaktivieren.

Zustellung

  • Antworte innerhalb von 15 Sekunden mit 2xx. Speichere das Event oder stelle es in eine Queue und verarbeite es später.
  • Nutze eine https-URL auf Port 443 mit einem öffentlichen Host. Aniva folgt keinen Weiterleitungen: Eine 3xx-Antwort zählt als Fehler.
  • Die Zustellung erfolgt mindestens einmal und ohne feste Reihenfolge. Verwirf Duplikate anhand der webhook-id. Nutze die Revisionen, um ältere Events zu ignorieren.
  • Antworte mit 410 Gone, um die Events zu stoppen. Aniva deaktiviert den Webhook sofort.
  • Aniva speichert Zustellungen 30 Tage lang. Danach kannst du sie nicht mehr auflisten oder erneut senden.

Wiederholungsversuche

Eine andere Antwort als 2xx, ein Timeout oder ein Netzwerkfehler löst einen Wiederholungsversuch aus. Jedes Event erhält bis zu 10 Versuche über etwa drei Tage: Nach Versuch 10 hat die Zustellung den Status failed. Sende sie über Zustellung erneut senden erneut. Sie behält dieselbe webhook-id.

Fehlerbenachrichtigungen

Aniva sendet eine E-Mail an die alert_emails des Webhooks, wenn 24 Stunden lang keine Zustellung erfolgreich war, wenn ein Event failed ist und wenn der Webhook deaktiviert wird. Nach 5 Tagen ohne erfolgreiche Zustellung deaktiviert Aniva den Webhook. Ein deaktivierter Webhook erhält keine neuen Events und seine wartenden Zustellungen werden abgebrochen. Um wieder zu starten, behebe das Problem an deinem Endpunkt und sende status: "enabled" über Webhook aktualisieren. Verpasste Events werden nicht automatisch erneut gesendet. Sende sie erneut oder lies den aktuellen Stand über die GET-Endpunkte aus.

Wiederholte Abrufe

Aniva speichert die Antwort einiger GET-Endpunkte für kurze Zeit. Wenn dein API-Schlüssel innerhalb dieser Zeit dieselbe Anfrage erneut sendet, erhältst du die gespeicherte Antwort. Du erhältst keinen Fehler und der Body hat dasselbe Format.
  • Ein Datensatz (eine Sendung, eine Heimtest-Kit-Bestellung, ein Termin sowie die Ergebnisse der letzten beiden): Bei jedem Aufruf prüft Aniva, ob der Datensatz unverändert ist. Hat er sich geändert, erhältst du eine frische Antwort.
  • Eine Liste kann älter sein als ihre Datensätze, höchstens jedoch 5 Minuten.
Um sofort von einer Änderung zu erfahren, nutze die Webhook-Events in der Tabelle.
  • Dieselbe Anfrage bedeutet derselbe API-Schlüssel, derselbe Endpunkt und dieselben Query-Parameter. Eine andere Seite einer Liste ist eine andere Anfrage und erhält eine eigene Antwort.
  • Aniva speichert nur eine 200-Antwort. Ein Fehler wird nie gespeichert.
  • Die Zeit beginnt, wenn Aniva die Antwort speichert. Ein späterer Aufruf verlängert sie nicht.
  • Nachdem dein API-Schlüssel etwas erstellt, aktualisiert, aktiviert oder storniert hat, ist dein nächster Abruf frisch. Auch der nächste Abruf dieses Datensatzes mit einem anderen deiner API-Schlüssel ist frisch.
  • In einer gespeicherten Sendungsantwort können die Felder synced_at und updated_at älter sein als in einer frischen Antwort. Status, Tracking und Adressen sind aktuell.
  • In einer gespeicherten Ergebnisantwort können ein Biomarker-Name, eine Einheit oder ein umgerechneter Wert bis zu 60 Minuten alt sein, nachdem Aniva den Katalog geändert hat. Die Messwerte sind aktuell.
  • Nachdem Aniva ein Webhook-Event für deinen Webhook erstellt hat, ist dein nächster Abruf dieses Datensatzes, seiner Ergebnisse und seiner Listen frisch. So zeigt der Abruf nach einem Event immer die Änderung.

Response-Header

Jede Antwort dieser Endpunkte für einen gültigen API-Schlüssel enthält diese Header:

Best Practices

  • Duplikate verwerfen. Überspringe ein Event, dessen webhook-id du bereits verarbeitet hast.
  • Revisionen nutzen. Speichere die höchste status_revision, results_revision und revision pro Objekt. Ignoriere ein Event mit einem niedrigeren Wert.
  • Die url abrufen. Das Event zeigt, dass sich etwas geändert hat. Der GET-Endpunkt zeigt, was.
  • Schnell antworten. Stelle das Event in eine Queue und antworte mit 2xx, bevor du es verarbeitest.
  • Abgleichen. Führe regelmäßig einen Job aus, der offene Objekte über die GET-Endpunkte abruft. Polling bleibt ein gültiger Fallback. Ein wiederholter Abruf kann eine gespeicherte Antwort liefern, siehe Wiederholte Abrufe.
  • Nach jedem Deployment testen. Nutze Test-Event senden.