Salt la conținutul principal
Un webhook este o cerere HTTPS 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ă

  1. Creează un endpoint HTTPS care acceptă POST și răspunde cu 2xx în cel mult 15 secunde.
  2. Înregistrează-l cu Creare webhook. Păstrează secret din răspuns. Aniva îl afișează o singură dată.
  3. Verifică semnătura fiecărei cereri.
  4. Trimite un eveniment de test. Verifică rezultatul în Listare livrări.
Cheia ta API are nevoie de scope-ul 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 endpointul GET 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 în pending trimite home_kit_order.pending.
  • O singură modificare poate trimite două evenimente cu același status_revision, de exemplu appointment.confirmed și appointment.rescheduled.
  • results.updated se 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 și results.fault vin întotdeauna împreună cu un results.updated cu același results_revision. Rezultatele se pot redeschide și finaliza din nou, așa că poți primi un al doilea results.completed.
Abonează-te la 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 evenimentul shipment.<status> cu același revision.

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
Un 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 headerele webhook-id, webhook-timestamp (secunde Unix) și webhook-signature.
  1. Ia corpul brut al cererii. Verifică-l înainte să parsezi JSON-ul.
  2. Construiește conținutul semnat {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Decodează din base64 partea secretului tău de după whsec_. Folosește-o ca cheie.
  4. Calculează HMAC-SHA256 pentru conținutul semnat și codifică-l în base64.
  5. Compară-l în timp constant cu fiecare intrare v1,<signature> din webhook-signature. Intrările sunt separate prin spații. O singură potrivire este suficientă.
  6. Respinge cererea când webhook-timestamp diferă cu mai mult de 5 minute față de ceasul tău.
Node.js
Schema este Standard Webhooks. Există biblioteci Standard Webhooks pentru majoritatea limbajelor și fac asta într-un singur apel.

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, trimite revoke_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 https pe portul 443 cu un host public. Aniva nu urmărește redirecționările: un răspuns 3xx contează 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 Gone pentru 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 de 2xx, 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 din alert_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-uri GET 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.
Pentru a afla imediat despre o modificare, folosește evenimentele webhook din tabel.
  • 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 și updated_at pot 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-id l-ai procesat deja.
  • Folosește reviziile. Stochează cele mai mari valori pentru status_revision, results_revision și revision per obiect. Ignoră un eveniment cu o valoare mai mică.
  • Interoghează url. Evenimentul indică faptul că ceva s-a schimbat. Endpoint-ul GET spune 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.