Saltar para o conteúdo principal
Um webhook é um 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

  1. Cria um endpoint HTTPS que aceite POST e responda 2xx no prazo de 15 segundos.
  2. Regista-o com Criar webhook. Guarda o secret da resposta. A Aniva mostra-o apenas uma vez.
  3. Verifica a assinatura de cada pedido.
  4. Envia um evento de teste. Verifica o resultado em Listar entregas.
A tua chave de API precisa do scope 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 endpoint GET 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 dispatched para pending envia home_kit_order.pending.
  • Uma alteração pode enviar dois eventos com o mesmo status_revision, por exemplo appointment.confirmed e appointment.rescheduled.
  • results.updated dispara 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.completed e results.fault vêm sempre com um results.updated do mesmo results_revision. Os resultados podem reabrir e ficar concluídos outra vez, por isso podes receber um segundo results.completed.
Subscreve 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.updated e o evento shipment.<status> com o mesmo revision.

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
Um 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çalhos webhook-id, webhook-timestamp (segundos Unix) e webhook-signature.
  1. Obtém o corpo do pedido em bruto. Verifica-o antes de analisares o JSON.
  2. Constrói o conteúdo assinado {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Descodifica em base64 a parte do teu segredo após whsec_. Usa-a como chave.
  4. Calcula o HMAC-SHA256 do conteúdo assinado e codifica-o em base64.
  5. Compara-o em tempo constante com cada entrada v1,<signature> em webhook-signature. As entradas estão separadas por espaços. Uma correspondência é suficiente.
  6. Rejeita o pedido quando webhook-timestamp diferir mais de 5 minutos do teu relógio.
Node.js
O esquema é Standard Webhooks. Existem bibliotecas Standard Webhooks para a maioria das linguagens e fazem isto numa só chamada.

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, envia revoke_current_secret_now: true para desativar o segredo antigo de imediato.

Entrega

  • Responde 2xx no prazo de 15 segundos. Guarda ou coloca o evento em fila e processa-o mais tarde.
  • Usa um URL https na porta 443 com um host público. A Aniva não segue redirecionamentos: um 3xx conta 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 Gone para 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 de 2xx, 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 os alert_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 endpoints GET 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.
Para saberes de uma alteração de imediato, usa os eventos de webhook na tabela.
  • 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_at e updated_at podem 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-id já tenhas processado.
  • Usa as revisões. Guarda os valores mais altos de status_revision, results_revision e revision por objeto. Ignora um evento com um valor inferior.
  • Obtém o url. O evento indica que algo mudou. O endpoint GET indica o quê.
  • Responde depressa. Coloca o evento em fila e responde 2xx antes 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.