POST pe care Aniva o trimite către serverul tău când se schimbă ceva. Nu trebuie
să faci polling.
Evenimentele sunt minimale. Conțin ID-ul obiectului, noul status, o revizie și url de citit. Nu
conțin niciodată valori de laborator sau date personale. Citește url cu cheia ta API pentru a obține datele.
Configurare rapidă
- Creează un endpoint HTTPS care acceptă
POSTși răspunde cu2xxîn cel mult 15 secunde. - Înregistrează-l cu Creare webhook.
Păstrează
secretdin răspuns. Aniva îl afișează o singură dată. - Verifică semnătura fiecărei cereri.
- Trimite un eveniment de test. Verifică rezultatul în Listare livrări.
webhooks_manage. Cere echipei Aniva să îl adauge. Un webhook aparține
cheii API care l-a creat, iar o cheie poate deține cel mult 5 webhookuri.
Evenimente
Primești un eveniment doar pentru obiectele pe care cheia ta API le poate citi cu endpointulGET corespunzător.
Alege tipurile cu enabled_events. Trimite ["*"] ca să primești toate tipurile, inclusiv pe cele adăugate ulterior.
- Un eveniment de status se declanșează la fiecare trecere în acel status, inclusiv la o revenire. De exemplu, un kit care
trece din
dispatchedînapoi înpendingtrimitehome_kit_order.pending. - O singură modificare poate trimite două evenimente cu același
status_revision, de exempluappointment.confirmedșiappointment.rescheduled. results.updatedse declanșează la fiecare modificare a rezultatelor: o valoare nouă, o corecție, o eroare, un document nou sau înlocuit ori o probă care părăsește obiectul. Sosește în câteva minute de la ultima modificare.results.completedșiresults.faultvin întotdeauna împreună cu unresults.updatedcu acelașiresults_revision. Rezultatele se pot redeschide și finaliza din nou, așa că poți primi un al doilearesults.completed.
results.updated ca să afișezi rezultate parțiale sau la results.completed ca să acționezi doar pe
rezultatele finale.
results.completed urmărește valorile rezultatelor, nu PDF-ul. PDF-ul raportului poate sosi înainte sau
după valori. Unele laboratoare trimit mai întâi un PDF preliminar și îl înlocuiesc ulterior cu cel final
sub același id de document. Înlocuirea trimite results.updated. Citește
documents[].original_file_name ca să le deosebești: Labor Quade termină un raport preliminar
(Vorbefund) în _V și raportul final (Endbefund) în _E, de exemplu
7642100312_B0012_FA_E.pdf.
Evenimentele pentru locații, profiluri și expedieri sosesc în câteva minute. Aniva așteaptă până când obiectul nu
s-a mai schimbat timp de 2 minute, astfel încât o serie de modificări trimite un singur eveniment. Se aplică și aceste reguli:
- Profilurile anonime nu trimit evenimente.
- O expediere nu trimite niciun eveniment când pierzi accesul la ea.
- O schimbare de status a expedierii trimite
shipment.updatedși evenimentulshipment.<status>cu acelașirevision.
Payload
Datele evenimentului de status
appointment.confirmed
Datele evenimentului de rezultate
home_kit_order.results.completed
Datele evenimentului de ștergere a documentului
document.deleted conține object (document), id, previous_results_status și
results_revision. Nu are url, pentru că nu mai rămâne nimic de citit.
document.deleted
Datele evenimentelor de locație, profil și expediere
shipment.in_transit
ping conține data.object webhook și data.id, ID-ul webhookului.
Verifică semnătura
Evenimentele nu conțin date, dar ar trebui totuși să îl verifici pe fiecare. O semnătură validă dovedește că evenimentul provine de la Aniva. Fiecare cerere include headerelewebhook-id, webhook-timestamp (secunde
Unix) și webhook-signature.
- Ia corpul brut al cererii. Verifică-l înainte să parsezi JSON-ul.
- Construiește conținutul semnat
{webhook-id}.{webhook-timestamp}.{raw body}. - Decodează din base64 partea secretului tău de după
whsec_. Folosește-o ca cheie. - Calculează HMAC-SHA256 pentru conținutul semnat și codifică-l în base64.
- Compară-l în timp constant cu fiecare intrare
v1,<signature>dinwebhook-signature. Intrările sunt separate prin spații. O singură potrivire este suficientă. - Respinge cererea când
webhook-timestampdiferă cu mai mult de 5 minute față de ceasul tău.
Node.js
Rotește secretul
Apelează Rotește secretul pentru a obține un secret nou. Timp de 24 de ore, Aniva semnează atât cu secretul vechi, cât și cu cel nou, așa că implementează-l pe cel nou în acest interval. După o scurgere, trimiterevoke_current_secret_now: true pentru a opri imediat secretul vechi.
Livrare
- Răspunde cu
2xxîn cel mult 15 secunde. Stochează evenimentul sau pune-l în coadă și procesează-l mai târziu. - Folosește un URL
httpspe portul 443 cu un host public. Aniva nu urmărește redirecționările: un răspuns3xxcontează ca eșec. - Livrarea se face cel puțin o dată și neordonat. Elimină duplicatele după
webhook-id. Folosește reviziile pentru a ignora un eveniment mai vechi. - Răspunde cu
410 Gonepentru a opri evenimentele. Aniva dezactivează imediat webhook-ul. - Aniva păstrează livrările timp de 30 de zile. După aceea, nu le mai poți lista sau retrimite.
Reîncercări
Un răspuns diferit de2xx, un timeout sau o eroare de rețea declanșează o reîncercare. Fiecare eveniment are până la 10 încercări
pe parcursul a aproximativ trei zile:
După încercarea 10, livrarea devine
failed. Trimite-o din nou cu
Retrimite livrarea. Păstrează același webhook-id.
Notificări de eșec
Aniva trimite un e-mail la adresele dinalert_emails ale webhook-ului atunci când nicio livrare nu a reușit timp de 24 de ore, când un eveniment este
failed și când webhook-ul este dezactivat. După 5 zile fără o livrare reușită, Aniva
dezactivează webhook-ul. Un webhook dezactivat nu primește evenimente noi, iar livrările sale în așteptare sunt
anulate.
Pentru a reporni, remediază endpoint-ul și trimite
status: "enabled" cu
Actualizează webhook-ul. Evenimentele pierdute nu sunt retrimise
automat. Retrimite-le sau citește starea curentă cu endpoint-urile GET.
Citiri repetate
Aniva stochează răspunsul unor endpoint-uriGET pentru o perioadă scurtă. Când cheia ta API trimite aceeași
cerere din nou în acest interval, primești răspunsul stocat. Nu primești nicio eroare, iar corpul răspunsului are
același format.
- O singură înregistrare (o expediere, o comandă de kit de testare la domiciliu, o programare și rezultatele ultimelor două): la fiecare apel, Aniva verifică dacă înregistrarea a rămas neschimbată. Dacă s-a schimbat, primești un răspuns nou.
- O listă poate fi mai veche decât înregistrările sale, cu cel mult 5 minute.
- Aceeași cerere înseamnă aceeași cheie API, același endpoint și aceiași parametri de interogare. O altă pagină a unei liste este o altă cerere și primește propriul răspuns.
- Aniva stochează doar un răspuns
200. O eroare nu este stocată niciodată. - Intervalul începe în momentul în care Aniva stochează răspunsul. Un apel ulterior nu îl prelungește.
- După ce cheia ta API creează, actualizează, activează sau anulează ceva, următoarea ta citire este nouă. Și următoarea citire a acelei înregistrări cu o altă cheie API a ta este nouă.
- Într-un răspuns stocat pentru o expediere, câmpurile
synced_atșiupdated_atpot fi mai vechi decât într-un răspuns nou. Statusul, urmărirea și adresele sunt actuale. - Într-un răspuns stocat pentru rezultate, numele unui biomarker, o unitate de măsură sau o valoare convertită pot fi mai vechi cu până la 60 de minute după ce Aniva își modifică catalogul. Valorile măsurate sunt actuale.
- După ce Aniva creează un eveniment webhook pentru webhook-ul tău, următoarea ta citire a acelei înregistrări, a rezultatelor sale și a listelor sale este nouă. Astfel, citirea care urmează unui eveniment arată întotdeauna modificarea.
Antete de răspuns
Fiecare răspuns al acestor endpoint-uri pentru o cheie API validă conține aceste antete:Bune practici
- Elimină duplicatele. Sari peste un eveniment al cărui
webhook-idl-ai procesat deja. - Folosește reviziile. Stochează cele mai mari valori pentru
status_revision,results_revisionșirevisionper obiect. Ignoră un eveniment cu o valoare mai mică. - Interoghează
url. Evenimentul indică faptul că ceva s-a schimbat. Endpoint-ulGETspune ce anume. - Răspunde rapid. Pune evenimentul în coadă și răspunde cu
2xxînainte să îl procesezi. - Reconciliază. Rulează un job periodic care citește obiectele deschise cu endpoint-urile
GET. Polling-ul rămâne o soluție de rezervă validă. O citire repetată poate primi un răspuns stocat, vezi Citiri repetate. - Testează după fiecare deploy. Folosește Trimite eveniment de test.