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
- Erstelle einen HTTPS-Endpunkt, der
POSTakzeptiert und innerhalb von 15 Sekunden mit2xxantwortet. - Registriere ihn über Webhook erstellen.
Speichere das
secretaus der Antwort. Aniva zeigt es nur einmal an. - Prüfe die Signatur jeder Anfrage.
- Sende ein Testereignis. Prüfe das Ergebnis unter Zustellungen auflisten.
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 passendenGET-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
dispatchedzurück inpendingwechselt,home_kit_order.pending. - Eine Änderung kann zwei Events mit derselben
status_revisionsenden, zum Beispielappointment.confirmedundappointment.rescheduled. results.updatedwird 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.completedundresults.faultkommen immer zusammen mit einemresults.updatedderselbenresults_revision. Ergebnisse können wieder geöffnet und erneut abgeschlossen werden, sodass du ein zweitesresults.completederhalten kannst.
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.updatedund dasshipment.<status>-Event mit derselbenrevision.
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
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 Headerwebhook-id,
webhook-timestamp (Unix-Sekunden) und webhook-signature.
- Nimm den unverarbeiteten Request-Body. Prüfe ihn, bevor du das JSON parst.
- Erstelle den signierten Inhalt
{webhook-id}.{webhook-timestamp}.{raw body}. - Dekodiere den Teil deines Secrets nach
whsec_per Base64. Verwende ihn als Schlüssel. - Berechne den HMAC-SHA256 des signierten Inhalts und kodiere ihn als Base64.
- Vergleiche ihn in konstanter Zeit mit jedem
v1,<signature>-Eintrag inwebhook-signature. Die Einträge sind durch Leerzeichen getrennt. Eine Übereinstimmung genügt. - Lehne die Anfrage ab, wenn
webhook-timestampmehr als 5 Minuten von deiner Uhr abweicht.
Node.js
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 durevoke_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: Eine3xx-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 als2xx, 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 diealert_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 einigerGET-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.
- 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_atundupdated_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-iddu bereits verarbeitet hast. - Revisionen nutzen. Speichere die höchste
status_revision,results_revisionundrevisionpro Objekt. Ignoriere ein Event mit einem niedrigeren Wert. - Die
urlabrufen. Das Event zeigt, dass sich etwas geändert hat. DerGET-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.