Webhooks

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.

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

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.

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.

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.

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 o plano de cuidado criado, e a saída chega como uma atualização do mesmo plano — revoked quando cancelado ou suspenso, completed quando concluído. 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.