É possível confiar neste webhook? Lista de verificação para aplicações autoalojadas
Antes de ligar um serviço externo a uma aplicação autoalojada, confirme na documentação da aplicação e da integração como são tratados os pedidos, os eventos, as permissões, os segredos e os registos.
Comece por identificar todos os webhooks de entrada
Um webhook é um ponto de entrada na aplicação. Antes de ativar um, registe o que sabe sobre o serviço que envia os pedidos, o endpoint e os efeitos que um evento pode desencadear.
Faça este levantamento separadamente para cada integração. Não presuma que a configuração de um endpoint descreve ou protege os restantes. As respostas dependem da aplicação, da versão e do serviço externo; confirme-as na documentação relevante.
- Remetente: que serviço deverá enviar pedidos e que método documentado permite verificar a sua origem?
- Endpoint: qual é o URL exato, a instância da aplicação e o ambiente?
- Eventos: que tipos de eventos pretende receber e quais estão configurados?
- Dados: que campos são enviados e podem conter informação pessoal, financeira ou operacionalmente sensível?
- Efeitos: que alterações, mensagens, chamadas de API ou outras ações podem decorrer de cada evento?
Confirme como a aplicação trata a autenticação do remetente
Procure na documentação da versão implementada e do serviço externo uma descrição do método usado para verificar os pedidos. Não deduza que um endpoint está autenticado apenas porque tem um URL difícil de adivinhar ou porque está acessível através de uma ligação protegida.
Verifique qual componente realiza a validação e o que acontece quando um pedido não passa essa verificação. Se a documentação não esclarecer estes pontos, registe-os como questões por resolver; não os trate como capacidades confirmadas.
- A documentação identifica um método de credencial ou assinatura para esta integração?
- Está explicado o que é verificado e como a verificação se associa ao pedido ou evento?
- Está documentado o comportamento perante pedidos sem credenciais ou com credenciais inválidas?
- A documentação aplica-se à versão e à configuração que utiliza?
- Se a verificação ocorrer numa camada externa à aplicação, está identificado quem a configura e mantém?
Verifique a validação do payload e os tipos de eventos
A validação da origem e a validação do conteúdo são perguntas distintas. Confirme na documentação e na configuração como a integração trata a estrutura e os valores do payload antes de desencadear ações.
Identifique quais tipos de eventos estão ativados e que ação corresponde a cada um. Se o comportamento perante eventos ou campos desconhecidos não estiver documentado, assinale essa lacuna em vez de presumir que são ignorados ou rejeitados.
- Que campos e formatos são esperados para cada tipo de evento?
- Há limites documentados para o tamanho dos pedidos e tratamento de corpos malformados?
- Como são verificados os identificadores e os registos referenciados no payload?
- Que tipos de eventos estão configurados e porquê?
- Que componente decide a ação a executar com base no conteúdo recebido?
Pergunte como são tratados pedidos antigos ou repetidos
Consulte a documentação do serviço externo e da aplicação para perceber se existem mecanismos documentados para identificar pedidos antigos ou repetidos e como o recetor os trata. Não presuma que uma verificação de origem, por si só, esclarece este comportamento.
A resposta pode variar entre integrações. Documente o comportamento esperado para eventos duplicados e confirme-o num ambiente seguro antes de depender dele.
- A integração documenta carimbos temporais, identificadores de evento ou outro mecanismo relacionado com pedidos repetidos?
- Está documentado se e como o recetor valida esses elementos?
- Como são tratados atrasos na entrega, diferenças entre relógios e reenvios?
- O que acontece se o mesmo evento for processado mais de uma vez?
- Se a aplicação não documentar estas capacidades, existe uma camada de integração identificada que as trate?
Identifique os limites das ações desencadeadas
Mapeie o percurso do pedido até à ação, incluindo as credenciais e os serviços ligados. Confirme na documentação da aplicação e da integração que permissões estão envolvidas e quem as pode alterar.
Considere separadamente o comportamento de um evento esperado, de um evento inesperado e de uma credencial comprometida. Não presuma que a existência de um webhook restringe automaticamente as ações que a integração pode executar.
- Que identidade, conta ou credencial é usada para executar ações?
- Que permissões e dados estão associados a essa identidade?
- Que ação corresponde a cada tipo de evento aceite?
- Que consequências poderia ter um evento inesperado ou uma alteração de configuração?
- O endpoint tem de estar acessível publicamente? Que restrições de acesso estão disponíveis e documentadas na implementação?
Documente o armazenamento e a rotação de segredos
Identifique os segredos e as credenciais associados à integração, onde são configurados e quem lhes pode aceder. Confirme na documentação da aplicação e do serviço externo como podem ser substituídos.
Registe o processo de rotação antes de precisar de o executar. Se os passos, o tempo de transição ou o comportamento das credenciais antigas não estiverem documentados, trate-os como pontos a esclarecer.
- Onde são guardados os segredos e quem pode consultá-los ou alterá-los?
- Podem aparecer em código, exportações de configuração, materiais de suporte ou diagnósticos?
- Que integração utiliza cada segredo?
- Quais são os passos documentados para substituir uma credencial em ambos os lados?
- Como pode confirmar que a configuração nova funciona e que a antiga deixou de ser aceite?
Confirme o que é registado e durante quanto tempo
Antes de depender dos registos para diagnosticar pedidos, confirme o que a aplicação e os componentes circundantes guardam. Cabeçalhos e payloads podem conter valores sensíveis; o comportamento concreto depende da configuração.
Registe quem pode consultar os dados, durante quanto tempo são conservados e como são tratadas cópias exportadas ou de segurança. Se estas respostas não estiverem disponíveis, assinale-as para validação com o responsável pela aplicação ou pelo alojamento.
- Os registos incluem corpos de pedidos, cabeçalhos, assinaturas, cadeias de consulta ou outros valores potencialmente sensíveis?
- Que informação pode ser usada para investigar um evento sem incluir o payload completo?
- Quem pode consultar os registos da aplicação, do proxy e da integração?
- Que prazos de retenção e regras de eliminação estão configurados?
- As mensagens de erro revelam segredos ou dados dos pedidos?
Separe os controlos da aplicação dos controlos de alojamento
Faça uma tabela que identifique o componente responsável por cada comportamento que pretende verificar: aplicação, serviço externo, proxy, camada de integração ou procedimento administrativo. A divisão depende da aplicação e da implementação; não presuma que um componente trata dos controlos dos outros.
As capacidades de alojamento indicadas pela Airbip incluem executar instâncias de aplicações como cargas de trabalho Docker em servidores cloud Airbip e automatizar o encaminhamento e os certificados TLS através do Traefik e do Let's Encrypt. Estes factos de alojamento não confirmam, por si só, como uma aplicação específica autentica pedidos, trata repetições ou limita as ações de um evento.
- Para cada comportamento que pretende confirmar, indique o componente responsável e a documentação consultada.
- Confirme qual componente trata pedidos que não passam uma verificação.
- Identifique quem pode alterar a exposição do endpoint, as credenciais e as ações configuradas.
- Se não conseguir confirmar um comportamento necessário, registe a lacuna e avalie se deve obter mais informação, acrescentar uma camada adequada ou não ativar a integração.
Perguntas frequentes
O HTTPS permite concluir que um webhook de entrada é fiável?
Não permite concluir como a aplicação verifica a origem do pedido nem como trata o evento. Confirme esses comportamentos separadamente na documentação da aplicação, do serviço externo e da implementação.
O que devo fazer se a aplicação não documentar assinaturas de webhook?
Não presuma que o endpoint está autenticado. Consulte a documentação da versão e da integração, identifique se outra camada trata da verificação e registe qualquer comportamento que não consiga confirmar. Se não conseguir esclarecer um requisito necessário, reavalie a exposição do endpoint.
Como posso avaliar um webhook sem arriscar dados de produção?
Procure um ambiente de teste e credenciais de teste documentados para a integração. Antes de testar, confirme que as ações não podem afetar utilizadores ou registos reais. Defina que comportamentos pretende verificar, como o tratamento de pedidos inválidos, repetidos ou com formatos inesperados, e confirme que os registos não expõem informação sensível.
É seguro incluir segredos de webhook e payloads nos registos?
Não presuma que é seguro. Verifique o que a aplicação e os serviços circundantes registam, quem pode consultar esses dados e durante quanto tempo são conservados. Se os registos incluírem informação sensível, esclareça como esse comportamento pode ser controlado.
Fontes e leituras adicionais
- Docker documentation — Docker
- Traefik documentation — Traefik Labs
- Let’s Encrypt documentation — Internet Security Research Group
- NIST Cybersecurity Framework — NIST
- OWASP Application Security Verification Standard — OWASP