> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.nilo.services/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.nilo.services/_mcp/server.

# Webhooks

> Por que as notificações pararam de chegar, por que uma assinatura não ativa e o que fazer com um evento perdido.

Quase todo problema de webhook é o mesmo problema: a assinatura **está desativada** e ninguém do
lado que recebe percebeu. Vale conhecer o mecanismo antes dos casos, porque ele explica todos
eles.

A Nilo desativa uma assinatura depois de uma sequência de falhas na entrega — é um **circuit
break**, e existe para que um endpoint fora do ar não trave a fila de entrega dos demais. A
reativação é automática, mas condicionada: a Nilo refaz o **aperto de mão** com o seu endpoint, e
só reativa se ele responder com sucesso. Um endpoint que continua falhando nunca é reativado, por
mais que o tempo passe.

O funcionamento completo está em [Webhooks](/guia/operacoes/webhooks).

## Paramos de receber notificações

**Causa.** A assinatura foi desativada pelo circuit break após falhas consecutivas na entrega, e
a reativação automática não passou porque o endpoint segue respondendo erro — inclusive ao aperto
de mão.

**O que fazer.** Nesta ordem:

1. **Confirme que o seu endpoint responde `2xx`** — tanto às notificações quanto ao payload de
   aperto de mão, que é diferente de uma notificação normal. É o passo que resolve a maioria dos
   casos: muitos endpoints tratam só a notificação e falham no aperto de mão.
2. **Consulte o status da assinatura** — veja
   [Consultar assinaturas](/guia/operacoes/webhooks#consultar-assinaturas). Uma assinatura
   desativada aparece com o erro que a desativou.
3. **Se o endpoint estiver íntegro e a assinatura não reativar**, abra um chamado.

> **Warning**
>
> Um endpoint que responde `500` durante uma janela de indisponibilidade **e volta ao ar** costuma
> ser reativado sozinho. Um que responde erro ao aperto de mão — porque não implementa esse
> payload, ou porque exige autenticação nele — fica desativado indefinidamente. Se você nunca
> testou o aperto de mão, teste-o antes de investigar qualquer outra coisa.

## A assinatura foi criada e nunca ativou

**Causa.** A URL não pôde ser validada no momento da inscrição — em geral porque o endpoint ainda
não estava no ar quando a assinatura foi criada.

**O que fazer.** Suba o endpoint primeiro, depois crie a assinatura. A validação acontece na
inscrição, não na primeira notificação.

## Um evento específico não chegou

**Causa.** Uma falha pontual na entrega daquele recurso, em geral um `5xx` momentâneo do lado que
recebe.

**O que fazer.** A entrega é retentada automaticamente, e na maioria dos casos a retentativa
resolve — confira se o evento não chegou depois, fora da ordem que você esperava. Se ele
realmente não chegou, abra um chamado com o recurso e o horário aproximado: é possível
reprocessar a entrega. Antes disso, confirme que o evento estava no escopo do `criteria` da sua
assinatura.

## Preciso de vários webhooks para o mesmo tipo de recurso

**Causa.** A regra é **uma assinatura viva por `criteria`**, e a comparação é da string inteira,
filtros incluídos. Duas assinaturas com filtros diferentes sobre o mesmo tipo de recurso são
permitidas justamente porque o `criteria` difere.

**O que fazer.** Diferencie os `criteria` com filtros de busca. O que não funciona é duas
assinaturas ativas com o `criteria` idêntico — desligue a primeira antes de criar a segunda. Veja
[`criteria` aceita filtros](/guia/operacoes/webhooks#criteria-aceita-filtros).

## A listagem mostra um status que não bate com o comportamento

**Causa.** A busca de assinatura por `criteria` pode devolver um status desatualizado.

**O que fazer.** Consulte a assinatura pelo identificador dela, que vem em `meta.tag`, e não pelo
`criteria`. Guarde esse identificador na criação — o `Subscription` não tem campo `identifier`, e
`meta.tag` é o que a substitui. Veja
[Consultar assinaturas](/guia/operacoes/webhooks#consultar-assinaturas).

## O que chega no endpoint não é o que eu esperava

**Causa.** `_include` e `_revinclude` no `criteria` mudam o **formato** da notificação: em vez do
recurso, chega um `Bundle` com o recurso e os relacionados.

**O que fazer.** Se você usa esses parâmetros, trate o corpo como `Bundle`. Se quer o recurso nu,
remova-os do `criteria`. Veja
[O que chega no seu endpoint](/guia/operacoes/webhooks#o-que-chega-no-seu-endpoint).

## Quero receber entrada e saída de linha de cuidado

**Causa de confusão.** Não há evento separado de saída.

**O que fazer.** Assine `CarePlan`. A entrada chega como a diretriz aplicada criada, e a saída
chega como uma **atualização da mesma diretriz aplicada** — `revoked` quando cancelada ou
suspensa, `completed` quando concluída. Trate a mudança de status, não a existência do recurso.

## O evento traz o profissional só como referência

**Causa.** As notificações trazem referências por identificador, não os recursos referenciados
por extenso.

**O que fazer.** Busque o recurso referenciado numa segunda requisição. Para profissional, veja
[Equipe de cuidado e profissionais](/guia/solucao-de-problemas/equipe-e-profissionais).