Vai al contenuto principale
Un webhook è una richiesta HTTPS POST che Aniva invia al tuo server quando cambia qualcosa. Non devi effettuare il polling. Gli eventi sono leggeri. Contengono l’ID dell’oggetto, il nuovo stato, una revisione e l’url da leggere. Non contengono mai valori di laboratorio o dati personali. Leggi l’url con la tua chiave API per ottenere i dati.

Configurazione rapida

  1. Crea un endpoint HTTPS che accetti POST e risponda 2xx entro 15 secondi.
  2. Registralo con Crea webhook. Salva il secret dalla risposta. Aniva lo mostra una sola volta.
  3. Verifica la firma di ogni richiesta.
  4. Invia un evento di test. Controlla il risultato in Elenca consegne.
La tua chiave API richiede lo scope webhooks_manage. Chiedi ad Aniva di aggiungerlo. Un webhook appartiene alla chiave API che lo ha creato e una chiave può avere al massimo 5 webhook.

Eventi

Ricevi un evento solo per gli oggetti che la tua chiave API può leggere con l’endpoint GET corrispondente. Scegli i tipi con enabled_events. Invia ["*"] per ricevere tutti i tipi, anche quelli aggiunti in seguito.
  • Un evento di stato si attiva a ogni passaggio a quello stato, anche tornando indietro. Per esempio, un kit che torna da dispatched a pending invia home_kit_order.pending.
  • Una singola modifica può inviare due eventi con la stessa status_revision, per esempio appointment.confirmed e appointment.rescheduled.
  • results.updated si attiva a ogni modifica dei risultati: un nuovo valore, una correzione, un errore, un documento nuovo o sostituito, o un campione che lascia l’oggetto. Arriva entro pochi minuti dall’ultima modifica.
  • results.completed e results.fault arrivano sempre insieme a un results.updated con la stessa results_revision. I risultati possono riaprirsi e completarsi di nuovo, quindi puoi ricevere un secondo results.completed.
Iscriviti a results.updated per mostrare risultati parziali, oppure a results.completed per agire solo sui risultati finali. results.completed segue i valori dei risultati, non il PDF. Il PDF del referto può arrivare prima o dopo i valori. Alcuni laboratori inviano prima un PDF preliminare e poi lo sostituiscono con quello definitivo mantenendo lo stesso id del documento. La sostituzione invia results.updated. Leggi documents[].original_file_name per distinguerli: Labor Quade termina il referto preliminare (Vorbefund) con _V e il referto definitivo (Endbefund) con _E, per esempio 7642100312_B0012_FA_E.pdf. Gli eventi di sedi, profili e spedizioni arrivano entro pochi minuti. Aniva aspetta che l’oggetto non cambi per 2 minuti, così più modifiche ravvicinate inviano un solo evento. Valgono anche queste regole:
  • I profili anonimi non inviano eventi.
  • Una spedizione non invia eventi quando perdi l’accesso.
  • Un cambio di stato di una spedizione invia shipment.updated e l’evento shipment.<status> con la stessa revision.

Payload

Dati degli eventi di stato

appointment.confirmed

Dati degli eventi sui risultati

home_kit_order.results.completed

Dati dell’evento di eliminazione documento

document.deleted contiene object (document), id, previous_results_status e results_revision. Non ha url, perché non rimane nulla da leggere.
document.deleted

Dati degli eventi di sedi, profili e spedizioni

shipment.in_transit
Un ping contiene data.object webhook e data.id, l’ID del webhook.

Verifica la firma

Gli eventi non contengono dati, ma dovresti comunque verificarli tutti. Una firma valida dimostra che l’evento proviene da Aniva. Ogni richiesta include gli header webhook-id, webhook-timestamp (secondi Unix) e webhook-signature.
  1. Prendi il corpo grezzo della richiesta. Verificalo prima di fare il parsing del JSON.
  2. Costruisci il contenuto firmato {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Decodifica in base64 la parte del tuo segreto dopo whsec_. Usala come chiave.
  4. Calcola l’HMAC-SHA256 del contenuto firmato e codificalo in base64.
  5. Confrontalo in tempo costante con ogni voce v1,<signature> in webhook-signature. Le voci sono separate da spazi. Basta una corrispondenza.
  6. Rifiuta la richiesta quando webhook-timestamp differisce di più di 5 minuti dal tuo orologio.
Node.js
Lo schema è Standard Webhooks. Esistono librerie Standard Webhooks per la maggior parte dei linguaggi che eseguono questa verifica in una sola chiamata.

Ruota il segreto

Chiama Ruota segreto per ottenere un nuovo segreto. Per 24 ore Aniva firma con il vecchio e il nuovo segreto, quindi distribuisci il nuovo entro quel tempo. Se il segreto viene compromesso, invia revoke_current_secret_now: true per disattivare subito quello vecchio.

Consegna

  • Rispondi con 2xx entro 15 secondi. Salva o metti in coda l’evento ed elaboralo in seguito.
  • Usa un URL https sulla porta 443 con un host pubblico. Aniva non segue i reindirizzamenti: un 3xx conta come fallimento.
  • La consegna è almeno una volta e non ordinata. Scarta i duplicati tramite webhook-id. Usa le revisioni per ignorare un evento più vecchio.
  • Rispondi con 410 Gone per interrompere gli eventi. Aniva disattiva subito il webhook.
  • Aniva conserva le consegne per 30 giorni. Dopo quel periodo, non puoi elencarle né reinviarle.

Nuovi tentativi

Una risposta diversa da 2xx, un timeout o un errore di rete avvia un nuovo tentativo. Ogni evento ha fino a 10 tentativi nell’arco di circa tre giorni: Dopo il tentativo 10, la consegna è failed. Inviala di nuovo con Reinvia consegna. Mantiene lo stesso webhook-id.

Avvisi di errore

Aniva invia un’email agli indirizzi in alert_emails del webhook quando nessuna consegna va a buon fine per 24 ore, quando un evento è failed e quando il webhook viene disattivato. Dopo 5 giorni senza consegne riuscite, Aniva disattiva il webhook. Un webhook disattivato non riceve nuovi eventi e le sue consegne in attesa vengono annullate. Per ricominciare, correggi il tuo endpoint e invia status: "enabled" con Aggiorna webhook. Gli eventi persi non vengono reinviati automaticamente. Reinviali, oppure leggi lo stato attuale con gli endpoint GET.

Letture ripetute

Aniva memorizza la risposta di alcuni endpoint GET per un breve periodo. Quando la tua chiave API invia di nuovo la stessa richiesta entro questo intervallo, ricevi la risposta memorizzata. Non ricevi alcun errore e il corpo ha lo stesso formato.
  • Un singolo record (una spedizione, un ordine di kit domiciliare, un appuntamento e i risultati degli ultimi due): a ogni chiamata, Aniva verifica che il record non sia cambiato. Se è cambiato, ricevi una risposta aggiornata.
  • Un elenco può essere meno recente dei suoi record, al massimo di 5 minuti.
Per sapere subito di una modifica, usa gli eventi webhook nella tabella.
  • Per stessa richiesta si intende la stessa chiave API, lo stesso endpoint e gli stessi parametri di query. Un’altra pagina di un elenco è un’altra richiesta e riceve la propria risposta.
  • Aniva memorizza solo una risposta 200. Un errore non viene mai memorizzato.
  • Il tempo inizia quando Aniva memorizza la risposta. Una chiamata successiva non lo prolunga.
  • Dopo che la tua chiave API crea, aggiorna, attiva o annulla qualcosa, la tua lettura successiva è aggiornata. Anche la lettura successiva di quel record con un’altra tua chiave API è aggiornata.
  • In una risposta memorizzata di una spedizione, i campi synced_at e updated_at possono essere meno recenti rispetto a una risposta aggiornata. Stato, tracciamento e indirizzi sono attuali.
  • In una risposta memorizzata dei risultati, il nome di un biomarcatore, un’unità o un valore convertito possono risalire fino a 60 minuti prima dopo una modifica al catalogo di Aniva. I valori misurati sono attuali.
  • Dopo che Aniva crea un evento webhook per il tuo webhook, la tua lettura successiva di quel record, dei suoi risultati e dei suoi elenchi è aggiornata. Così la lettura che segue un evento mostra sempre la modifica.

Header di risposta

Ogni risposta di questi endpoint a una chiave API valida contiene questi header:

Buone pratiche

  • Scarta i duplicati. Salta un evento con un webhook-id che hai già elaborato.
  • Usa le revisioni. Salva il valore più alto di status_revision, results_revision e revision per oggetto. Ignora un evento con un valore inferiore.
  • Recupera l’url. L’evento dice che qualcosa è cambiato. L’endpoint GET dice cosa.
  • Rispondi in fretta. Metti in coda l’evento e rispondi con 2xx prima di elaborarlo.
  • Riconcilia. Esegui un job periodico che legge gli oggetti aperti con gli endpoint GET. Il polling resta un valido fallback. Una lettura ripetuta può ricevere una risposta memorizzata, vedi Letture ripetute.
  • Fai un test dopo ogni deploy. Usa Invia evento di test.