> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Recebe uma chamada HTTPS da Aniva quando há alterações numa marcação, numa encomenda de kit de teste em casa, nos respetivos resultados, num documento carregado, num local, num perfil ou num envio

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](https://docs.anivahealth.com/pt/api/webhooks/create-webhook.md).
   Guarda o `secret` da resposta. A Aniva mostra-o apenas uma vez.
3. [Verifica a assinatura](#verificar-a-assinatura) de cada pedido.
4. Envia um [evento de teste](https://docs.anivahealth.com/pt/api/webhooks/send-test-event.md). Verifica o resultado em
   [Listar entregas](https://docs.anivahealth.com/pt/api/webhooks/list-deliveries.md).

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.

| Tipo | Quando dispara |
| - | - |
| `appointment.created` | A marcação fica visível para ti. Enviado uma vez por marcação. |
| `appointment.pending` | A marcação passa para `pending`. |
| `appointment.confirmed` | A marcação passa para `confirmed`. |
| `appointment.blood_drawn` | A marcação passa para `blood_drawn`. |
| `appointment.cancelled` | A marcação passa para `cancelled`. |
| `appointment.rescheduled` | `scheduled_at` ou o local muda. Não é enviado quando a marcação está `cancelled`. |
| `appointment.results.updated` | Os resultados mudam. |
| `appointment.results.completed` | O `status` dos resultados passa para `completed`. |
| `appointment.results.fault` | O `status` dos resultados passa para `fault`. |
| `home_kit_order.created` | A encomenda é criada. Enviado uma vez por encomenda. |
| `home_kit_order.pending` | A encomenda passa para `pending`. |
| `home_kit_order.dispatched` | A encomenda passa para `dispatched`. |
| `home_kit_order.activated` | A encomenda passa para `activated`. |
| `home_kit_order.cancelled` | A encomenda passa para `cancelled`. |
| `home_kit_order.results.updated` | Os resultados mudam. |
| `home_kit_order.results.completed` | O `status` dos resultados passa para `completed`. |
| `home_kit_order.results.fault` | O `status` dos resultados passa para `fault`. |
| `document.results.updated` | Os resultados de um documento que carregaste mudam, ou este é armazenado. `stored` é final: não se segue `document.results.completed`. |
| `document.results.completed` | O `status` dos resultados de um documento que carregaste passa para `completed`. |
| `document.results.fault` | O `status` dos resultados de um documento que carregaste passa para `fault`. |
| `document.deleted` | Um documento que carregaste é eliminado. Enviado aos endpoints que receberam o seu último evento de resultados. Sem `url`. |
| `location.created` | O local fica visível para ti: novo, ativado ou adicionado a um grupo que lês. |
| `location.updated` | Qualquer campo do local muda: nome, morada, website, horário de funcionamento, imagem. |
| `location.deactivated` | Já não podes ler o local. |
| `location.retail_prices.updated` | O preço publicado de um painel ou biomarcador no local muda. Precisa do scope `retail_prices_view`. |
| `profile.created` | O perfil fica visível para ti: novo ou adicionado a um grupo de perfis que lês. |
| `profile.updated` | Qualquer campo de [Obter perfil](https://docs.anivahealth.com/pt/api/profiles/get-profile.md) muda. |
| `profile.deleted` | O perfil é eliminado ou já não o podes ler. |
| `shipment.created` | O envio fica visível para ti. |
| `shipment.updated` | Qualquer campo do envio muda: seguimento, leituras, recolha, notas, links. |
| `shipment.pending` | O envio passa para `pending`. |
| `shipment.in_transit` | O envio passa para `in_transit`. |
| `shipment.delivered` | O envio passa para `delivered`. |
| `shipment.fault` | O envio passa para `fault`. |
| `shipment.cancelled` | O envio passa para `cancelled`. |
| `ping` | Enviaste um evento de teste. Sempre enviado, não faz parte de `enabled_events`. |

* 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

| Campo | Descrição |
| - | - |
| `id` | ID do evento (UUID). Igual ao cabeçalho `webhook-id`. Mantém-se igual em novas tentativas e reenvios. |
| `type` | Tipo de evento, por exemplo `appointment.confirmed`. |
| `timestamp` | Quando a alteração ocorreu, como instante ISO 8601 UTC. Não é a hora do envio. |
| `data` | O objeto alterado. A estrutura depende do tipo de evento. |

### Dados de eventos de estado

| Campo | Descrição |
| - | - |
| `object` | `appointment` ou `home_kit_order`. |
| `id` | O ID da marcação ou da encomenda de kit de teste em casa (UUID). |
| `url` | `/api/v1/appointments/{id}` ou `/api/v1/home-kit-orders/{id}`. |
| `status` | O estado após a alteração. |
| `previous_status` | O estado antes da alteração. `null` em `created`. |
| `status_revision` | Contador por objeto. Sobe a cada alteração de estado e pode saltar números. |

```json appointment.confirmed theme={null}
{
  "id": "0b8e6f3a-2c4d-4e7f-9a1b-3c5d7e9f1a2b",
  "type": "appointment.confirmed",
  "timestamp": "2026-10-15T09:12:44.512Z",
  "data": {
    "object": "appointment",
    "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "url": "https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "status": "confirmed",
    "previous_status": "pending",
    "status_revision": 2
  }
}
```

### Dados de eventos de resultados

| Campo | Descrição |
| - | - |
| `object` | `appointment`, `home_kit_order` ou `document`. |
| `id` | O ID da marcação, da encomenda de kit de teste em casa ou do documento (UUID). |
| `url` | A rota `/results` do objeto, p. ex. `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` ou `fault`. Um documento também pode estar `stored`. |
| `previous_results_status` | O `results_status` do evento de resultados anterior. `null` no primeiro. |
| `results_revision` | Contador por objeto. Sobe a cada alteração de resultados e pode saltar números. |

```json home_kit_order.results.completed theme={null}
{
  "id": "6d2a9c4e-8f1b-4a3d-b5e7-0c2f4a6b8d1e",
  "type": "home_kit_order.results.completed",
  "timestamp": "2026-10-15T14:03:00.000Z",
  "data": {
    "object": "home_kit_order",
    "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "url": "https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/results",
    "results_status": "completed",
    "previous_results_status": "in_progress",
    "results_revision": 4
  }
}
```

### 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.

```json document.deleted theme={null}
{
  "id": "1c9e7a52-3f4b-4d8a-9e61-7b2c5d0f8a14",
  "type": "document.deleted",
  "timestamp": "2026-10-24T09:12:00.000Z",
  "data": {
    "object": "document",
    "id": "f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c",
    "previous_results_status": "completed",
    "results_revision": 3
  }
}
```

### Dados de eventos de local, perfil e envio

| Campo | Descrição |
| - | - |
| `object` | `location`, `profile` ou `shipment`. |
| `id` | O ID do local ou do perfil (UUID), ou a referência do envio. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` ou `/api/v1/shipments/{id}`. Ausente em `.deactivated` e `.deleted`. |
| `status` | Apenas envios. O estado após a alteração. |
| `previous_status` | Apenas envios. O estado antes da alteração. `null` em `shipment.created`. |
| `revision` | Contador por objeto em todos os seus eventos. Pode saltar números. Os eventos de preços de venda ao público têm o seu próprio contador. |

```json shipment.in_transit theme={null}
{
  "id": "3f7c1a2b-9d4e-4b6a-8c5f-2e1d0a9b8c7d",
  "type": "shipment.in_transit",
  "timestamp": "2026-10-16T08:41:12.000Z",
  "data": {
    "object": "shipment",
    "id": "P2610164821",
    "url": "https://anivahealth.com/api/v1/shipments/P2610164821",
    "status": "in_transit",
    "previous_status": "pending",
    "revision": 3
  }
}
```

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.

```typescript Node.js theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyAnivaWebhook(rawBody: string, headers: Headers, secret: string): boolean {
  const id = headers.get('webhook-id') ?? '';
  const timestamp = headers.get('webhook-timestamp') ?? '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();

  return (headers.get('webhook-signature') ?? '').split(' ').some((entry) => {
    const [version, signature = ''] = entry.split(',');
    const received = Buffer.from(signature, 'base64');
    return (
      version === 'v1' && received.length === expected.length && timingSafeEqual(received, expected)
    );
  });
}
```

O esquema é [Standard Webhooks](https://www.standardwebhooks.com). Existem bibliotecas Standard Webhooks
para a maioria das linguagens e fazem isto numa só chamada.

### Rodar o segredo

Chama [Rodar segredo](https://docs.anivahealth.com/pt/api/webhooks/rotate-secret.md) 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:

| Tentativa | Tempo após a primeira tentativa |
| - | - |
| 2 | cerca de 5 segundos |
| 3 | cerca de 5 minutos |
| 4 | cerca de 35 minutos |
| 5 | cerca de 2,5 horas |
| 6 | cerca de 7,5 horas |
| 7 | cerca de 17,5 horas |
| 8 | cerca de 27,5 horas |
| 9 | cerca de 51,5 horas |
| 10 | cerca de 75,5 horas |

Após a tentativa 10, a entrega passa a `failed`. Envia-a novamente com
[Reenviar entrega](https://docs.anivahealth.com/pt/api/webhooks/resend-delivery.md). 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.

| `disabled_reason` | Causa |
| - | - |
| `Disabled by the partner` | Enviaste `status: "disabled"`. |
| `Disabled by Aniva` | A Aniva desativou o webhook. Só a Aniva pode voltar a ativá-lo. |
| `The endpoint answered 410 Gone` | O teu endpoint respondeu `410 Gone`. |
| `No successful delivery for 5 days` | Nenhuma entrega teve sucesso durante 5 dias. |

Para recomeçar, corrige o teu endpoint e envia `status: "enabled"` com
[Atualizar webhook](https://docs.anivahealth.com/pt/api/webhooks/update-webhook.md). 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.

| Endpoint | Guardado durante | Eventos que te avisam de uma alteração |
| - | - | - |
| [Obter envio](https://docs.anivahealth.com/pt/api/shipments/get-shipment.md) | 60 minutos | `shipment.created`, `shipment.updated` |
| [Listar envios](https://docs.anivahealth.com/pt/api/shipments/list-shipments.md) | 5 minutos | `shipment.created`, `shipment.updated` |
| [Obter encomenda de kit de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/get-home-kit.md) | 60 minutos | `home_kit_order.created` e um evento por estado, por exemplo `home_kit_order.activated` |
| [Obter resultados da encomenda de kit de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/get-results.md) | 60 minutos | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Listar encomendas de kits de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/list-home-kits.md) | 5 minutos | os mesmos eventos de uma encomenda de kit de teste em casa |
| [Obter marcação](https://docs.anivahealth.com/pt/api/appointments/get-appointment.md) | 15 minutos | `appointment.created`, `appointment.rescheduled` e um evento por estado, por exemplo `appointment.confirmed` |
| [Obter resultados da marcação](https://docs.anivahealth.com/pt/api/appointments/get-results.md) | 60 minutos | `appointment.results.updated`, `.completed`, `.fault` |
| [Listar marcações](https://docs.anivahealth.com/pt/api/appointments/list-appointments.md) | 5 minutos | os mesmos eventos de uma marcação |
| [Listar perfis](https://docs.anivahealth.com/pt/api/profiles/list-profiles.md) | 5 minutos | `profile.created`, `profile.updated`, `profile.deleted` |

* 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:

| Cabeçalho | Enviado com | Significado |
| - | - | - |
| `Aniva-Webhook-Events` | Cada resposta | Os eventos de webhook que abrangem o endpoint, separados por vírgulas. |
| `Link` | Cada resposta | O endereço desta página, com `rel="help"`. |
| `Cache-Status` | Uma resposta `200` | `Aniva; hit; ttl=3476` é uma resposta guardada. `ttl` é o número de segundos até estar disponível uma resposta atualizada. `Aniva; fwd=miss; stored; ttl=3600` é uma resposta atualizada que a Aniva guardou agora. `Aniva; fwd=miss` é uma resposta atualizada que a Aniva não guardou. |
| `Age` | Uma resposta guardada | A idade da resposta guardada em segundos. |
| `Cache-Control` | Uma resposta `200` | `private, no-cache`. Não guardes a resposta numa cache própria em vez de fazeres uma chamada à Aniva. |

```http theme={null}
HTTP/1.1 200 OK
Age: 124
Cache-Status: Aniva; hit; ttl=3476
Cache-Control: private, no-cache
Aniva-Webhook-Events: shipment.created, shipment.updated
Link: <https://docs.anivahealth.com/concepts/webhooks>; rel="help"
```

## 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](#leituras-repetidas).
* **Testa após cada implementação.** Usa [Enviar evento de teste](https://docs.anivahealth.com/pt/api/webhooks/send-test-event.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.