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
- Crea un endpoint HTTPS che accetti
POSTe risponda2xxentro 15 secondi. - Registralo con Crea webhook.
Salva il
secretdalla risposta. Aniva lo mostra una sola volta. - Verifica la firma di ogni richiesta.
- Invia un evento di test. Controlla il risultato in Elenca consegne.
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’endpointGET 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
dispatchedapendinginviahome_kit_order.pending. - Una singola modifica può inviare due eventi con la stessa
status_revision, per esempioappointment.confirmedeappointment.rescheduled. results.updatedsi 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.completederesults.faultarrivano sempre insieme a unresults.updatedcon la stessaresults_revision. I risultati possono riaprirsi e completarsi di nuovo, quindi puoi ricevere un secondoresults.completed.
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.updatede l’eventoshipment.<status>con la stessarevision.
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
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 headerwebhook-id, webhook-timestamp
(secondi Unix) e webhook-signature.
- Prendi il corpo grezzo della richiesta. Verificalo prima di fare il parsing del JSON.
- Costruisci il contenuto firmato
{webhook-id}.{webhook-timestamp}.{raw body}. - Decodifica in base64 la parte del tuo segreto dopo
whsec_. Usala come chiave. - Calcola l’HMAC-SHA256 del contenuto firmato e codificalo in base64.
- Confrontalo in tempo costante con ogni voce
v1,<signature>inwebhook-signature. Le voci sono separate da spazi. Basta una corrispondenza. - Rifiuta la richiesta quando
webhook-timestampdifferisce di più di 5 minuti dal tuo orologio.
Node.js
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, inviarevoke_current_secret_now: true per disattivare subito quello
vecchio.
Consegna
- Rispondi con
2xxentro 15 secondi. Salva o metti in coda l’evento ed elaboralo in seguito. - Usa un URL
httpssulla porta 443 con un host pubblico. Aniva non segue i reindirizzamenti: un3xxconta 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 Goneper 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 da2xx, 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 inalert_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 endpointGET 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 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_ateupdated_atpossono 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-idche hai già elaborato. - Usa le revisioni. Salva il valore più alto di
status_revision,results_revisionerevisionper oggetto. Ignora un evento con un valore inferiore. - Recupera l’
url. L’evento dice che qualcosa è cambiato. L’endpointGETdice cosa. - Rispondi in fretta. Metti in coda l’evento e rispondi con
2xxprima 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.