POST HTTPS que a Aniva envia para o teu servidor quando algo muda. Não precisas
de fazer polling.
Os eventos são leves. Trazem o ID do objeto, o novo estado, uma revisão e o url a ler. Nunca
trazem valores laboratoriais nem dados pessoais. Lê o url com a tua chave de API para obter os dados.
Configuração rápida
- Cria um endpoint HTTPS que aceite
POSTe responda2xxno prazo de 15 segundos. - Regista-o com Criar webhook.
Guarda o
secretda resposta. A Aniva mostra-o apenas uma vez. - Verifica a assinatura de cada pedido.
- Envia um evento de teste. Verifica o resultado em Listar entregas.
webhooks_manage. Pede à Aniva para o adicionar. Um webhook pertence à
chave de API que o criou, e uma chave pode ter no máximo 5 webhooks.
Eventos
Recebes um evento apenas para objetos que a tua chave de API pode ler com o endpointGET correspondente.
Escolhe os tipos com enabled_events. Envia ["*"] para receberes todos os tipos, incluindo tipos adicionados mais tarde.
- Um evento de estado dispara em cada passagem para esse estado, mesmo quando volta atrás. Por exemplo, um kit que
volta de
dispatchedparapendingenviahome_kit_order.pending. - Uma alteração pode enviar dois eventos com o mesmo
status_revision, por exemploappointment.confirmedeappointment.rescheduled. results.updateddispara em cada alteração dos resultados: um novo valor, uma correção, uma falha, um documento novo ou substituído, ou uma amostra que sai do objeto. Chega poucos minutos após a última alteração.results.completederesults.faultvêm sempre com umresults.updateddo mesmoresults_revision. Os resultados podem reabrir e ficar concluídos outra vez, por isso podes receber um segundoresults.completed.
results.updated para mostrar resultados parciais, ou results.completed para agir apenas sobre
resultados finais.
results.completed segue os valores dos resultados, não o PDF. O PDF do relatório pode chegar antes ou
depois dos valores. Alguns laboratórios enviam primeiro um PDF preliminar e mais tarde substituem-no pelo final
com o mesmo id de documento. A substituição envia results.updated. Lê
documents[].original_file_name para distinguir os dois: Labor Quade termina um relatório preliminar
(Vorbefund) em _V e o relatório final (Endbefund) em _E, por exemplo
7642100312_B0012_FA_E.pdf.
Os eventos de local, perfil e envio chegam dentro de poucos minutos. A Aniva espera até o objeto ficar
2 minutos sem alterações, por isso várias edições seguidas enviam um só evento. Também se aplicam estas regras:
- Perfis anónimos não enviam eventos.
- Um envio não envia nenhum evento quando perdes acesso a ele.
- Uma alteração de estado de um envio envia
shipment.updatede o eventoshipment.<status>com o mesmorevision.
Payload
Dados de eventos de estado
appointment.confirmed
Dados de eventos de resultados
home_kit_order.results.completed
Dados de eventos de documento eliminado
document.deleted inclui object (document), id, previous_results_status e
results_revision. Não tem url, porque já não há nada para ler.
document.deleted
Dados de eventos de local, perfil e envio
shipment.in_transit
ping inclui data.object webhook e data.id, o ID do webhook.
Verificar a assinatura
Os eventos não incluem dados, mas deves verificar cada um na mesma. Uma assinatura válida prova que o evento veio da Aniva. Cada pedido inclui os cabeçalhoswebhook-id, webhook-timestamp (segundos
Unix) e webhook-signature.
- Obtém o corpo do pedido em bruto. Verifica-o antes de analisares o JSON.
- Constrói o conteúdo assinado
{webhook-id}.{webhook-timestamp}.{raw body}. - Descodifica em base64 a parte do teu segredo após
whsec_. Usa-a como chave. - Calcula o HMAC-SHA256 do conteúdo assinado e codifica-o em base64.
- Compara-o em tempo constante com cada entrada
v1,<signature>emwebhook-signature. As entradas estão separadas por espaços. Uma correspondência é suficiente. - Rejeita o pedido quando
webhook-timestampdiferir mais de 5 minutos do teu relógio.
Node.js
Rodar o segredo
Chama Rodar segredo para obter um novo segredo. Durante 24 horas, a Aniva assina com o segredo antigo e com o novo, por isso implementa o novo dentro desse prazo. Após uma fuga, enviarevoke_current_secret_now: true para desativar o segredo antigo de imediato.
Entrega
- Responde
2xxno prazo de 15 segundos. Guarda ou coloca o evento em fila e processa-o mais tarde. - Usa um URL
httpsna porta 443 com um host público. A Aniva não segue redirecionamentos: um3xxconta como falha. - A entrega é feita pelo menos uma vez e sem ordem garantida. Descarta duplicados pelo
webhook-id. Usa as revisões para ignorar um evento mais antigo. - Responde
410 Gonepara parar os eventos. A Aniva desativa o webhook de imediato. - A Aniva guarda as entregas durante 30 dias. Depois disso, não podes listá-las nem reenviá-las.
Novas tentativas
Uma resposta diferente de2xx, um timeout ou um erro de rede inicia uma nova tentativa. Cada evento tem até 10 tentativas
ao longo de cerca de três dias:
Após a tentativa 10, a entrega passa a
failed. Envia-a novamente com
Reenviar entrega. Mantém o mesmo webhook-id.
Avisos de falha
A Aniva envia um email para osalert_emails do webhook quando nenhuma entrega tem sucesso durante 24 horas, quando um evento fica
failed e quando o webhook é desativado. Após 5 dias sem uma entrega bem-sucedida, a Aniva
desativa o webhook. Um webhook desativado não recebe novos eventos e as suas entregas em espera são
canceladas.
Para recomeçar, corrige o teu endpoint e envia
status: "enabled" com
Atualizar webhook. Os eventos perdidos não são enviados
novamente de forma automática. Reenvia-os ou lê o estado atual com os endpoints GET.
Leituras repetidas
A Aniva guarda a resposta de alguns endpointsGET durante um curto período. Quando a tua chave API envia o mesmo
pedido novamente dentro desse período, recebes a resposta guardada. Não recebes nenhum erro e o corpo tem o
mesmo formato.
- Um registo (um envio, uma encomenda de kit de teste em casa, uma marcação e os resultados dos dois últimos): em cada chamada, a Aniva verifica se o registo permanece inalterado. Se tiver mudado, recebes uma resposta atualizada.
- Uma lista pode ser mais antiga do que os seus registos, no máximo 5 minutos.
- O mesmo pedido consiste na mesma chave API, no mesmo endpoint e nos mesmos parâmetros de consulta. Outra página de uma lista é outro pedido e recebe a sua própria resposta.
- A Aniva guarda apenas respostas
200. Um erro nunca é guardado. - A contagem do tempo começa quando a Aniva guarda a resposta. Uma chamada posterior não prolonga esse tempo.
- Depois de a tua chave API criar, atualizar, ativar ou cancelar algo, a tua leitura seguinte é atualizada. A leitura seguinte desse registo com outra das tuas chaves API também é atualizada.
- Numa resposta de envio guardada, os campos
synced_ateupdated_atpodem ser mais antigos do que numa resposta atualizada. O estado, o seguimento e as moradas estão atualizados. - Numa resposta de resultados guardada, o nome de um biomarcador, uma unidade ou um valor convertido podem ter até 60 minutos de atraso após a Aniva alterar o seu catálogo. Os valores medidos estão atualizados.
- Depois de a Aniva criar um evento de webhook para o teu webhook, a tua leitura seguinte desse registo, dos seus resultados e das suas listas é atualizada. Assim, a leitura que se segue a um evento mostra sempre a alteração.
Cabeçalhos de resposta
Cada resposta destes endpoints a uma chave API válida inclui estes cabeçalhos:Boas práticas
- Descarta duplicados. Ignora um evento cujo
webhook-idjá tenhas processado. - Usa as revisões. Guarda os valores mais altos de
status_revision,results_revisionerevisionpor objeto. Ignora um evento com um valor inferior. - Obtém o
url. O evento indica que algo mudou. O endpointGETindica o quê. - Responde depressa. Coloca o evento em fila e responde
2xxantes de o processares. - Reconcilia. Executa uma tarefa regular que leia objetos abertos com os endpoints
GET. O polling continua a ser uma alternativa válida. Uma leitura repetida pode devolver uma resposta guardada, consulta Leituras repetidas. - Testa após cada implementação. Usa Enviar evento de teste.