Checklist de segurança de Webhook: Como construir webhooks seguros

Por que você está aqui?

Não vamos perder tempo. Você está aqui porque está construindo um recurso de webhook em seu aplicativo. Infelizmente, há muitas coisas que podem dar errado sob uma perspectiva de segurança. Este artigo visa garantir que você não esteja cometendo erros conhecidos ao construir webhooks.

Como funcionam os webhooks?

Em um breve resumo, webhooks são requisições HTTP(S) para terceiros para informá-los sobre algo que aconteceu em seu aplicativo. Por exemplo, se você oferece um aplicativo que gera faturas, pode oferecer aos seus clientes a oportunidade de configurar a funcionalidade de webhook que é acionada quando uma nova fatura é criada. Isso significa que, quando a fatura é criada, seu aplicativo enviará uma requisição HTTP(S) para um local determinado pelo usuário. O usuário pode usar isso para configurar seus próprios fluxos de trabalho personalizados que são acionados pelo webhook, como agendar e-mails de lembrete ou enviar uma mensagem ao cliente no Slack.

Checklist: segurança em implementações de webhook

1. Combatendo ataques do tipo SSRF

Nesse tipo de ataque, o atacante tenta obter informações (por exemplo, metadados de instância em uma Cloud) explorando o recurso de webhook. Para combatê-lo, você deve tomar as seguintes medidas.

✅ Validar entrada do usuário

• Básico: Realiza validação simples de URL.
• Melhor: Garanta que a URL comece com "https://", não permita "file://" e outros esquemas não-HTTPS.

✅ Restringir Endereços Locais

• Bloquear IPs locais típicos: 127.0.x, 192.168.x, 172.x.
• Proibir "localhost" e "http://"

✅ Limitar Exposição de Logs

• Exibir apenas códigos de status HTTP em logs visíveis para o usuário.
• Evite exibir cabeçalhos ou conteúdo do corpo.

✅ Avançado: Validação de URL aprimorada

• Exigir um cabeçalho de resposta específico para requisições POST, exclusivo para o cliente.
• Mantenha esta verificação continuamente, mesmo após a configuração inicial, para neutralizar alterações de DNS.

2. Permita que seus usuários verifiquem a autenticidade dos dados

Seu consumidor de webhook deve ter uma forma de saber que os dados realmente vêm do seu aplicativo. Você pode usar qualquer um dos seguintes métodos.

✅ Verificação de Mensagens de Teste

Primeiro, permita que os usuários acionem uma mensagem de teste para testar mecanismos de segurança.

✅ Hash de Verificação HMAC

Um dos mecanismos de segurança mais eficazes para funcionalidades de webhooks é a implementação de HMAC para integridade e autenticidade dos dados.

O processo básico pode ser resumido da seguinte forma:

• Gere um hash do payload usando SHA-256 e uma chave secreta.
• Enviar o HMAC com o payload.
• Os destinatários recriam o hash para verificar a autenticidade e integridade do payload.

✅ Inclusão de Timestamp

Esta é uma mitigação de segurança mais avançada. Adicione um timestamp ao payload para prevenir ataques de replay. Garante que as mensagens não sejam reutilizadas ou alteradas.

✅ Certificados TLS do Lado do Cliente

Autentique chamadas HTTP com certificados TLS do lado do cliente. Isso é particularmente atraente para consumidores de nível empresarial.

3. Limitar a taxa e evitar a superexposição de dados

Para a segurança de webhooks, enviar poucos dados é mais seguro do que anexar muitos. Embora os callbacks de webhook devam ser criptografados usando HTTPS, nunca se sabe quem pode estar no controle de um nome de domínio depois de alguns anos.

✅ Minimizar Exposição de Dados

• Evite enviar Informações de Identificação Pessoal (PII) ou dados sensíveis.
• Em vez de enviar múltiplos pontos de dados (como contact_id, email, nome), apenas envie o contact_id. Permita que os usuários busquem dados adicionais através de sua API pública, se necessário.

✅ Comunicação da Política de Retentativa

• Comunicar claramente a política de retentativas e os limites de taxa aos usuários.
• Informe-os de que, devido a novas tentativas, as mensagens podem chegar fora de ordem.
• Defina que qualquer resposta 2xx é um sucesso; outras respostas devem acionar uma nova tentativa.

✅ Usar um Sistema de Fila para Entrega

Implemente um sistema de fila para gerenciar a entrega de webhooks e limitar a saída. Essa abordagem ajuda a evitar sobrecarregar acidentalmente os servidores dos seus usuários em casos extremos, como uma grande importação de CSV que aciona chamadas de webhook e novas tentativas excessivas.

4. Bônus: Alerta de anomalias

Isso é mais para conveniência do desenvolvedor do que para segurança, mas é algo bom de implementar, de qualquer forma.

• Alertar usuários quando respostas 4xx e 5xx são encontradas
• Enviar notificações para informar os usuários sobre quaisquer falhas

Essa adição aumenta a transparência e a capacidade de resposta em seu sistema de webhook.

Conclusão

E pronto! Cobrimos algumas etapas para tornar seus webhooks não apenas funcionais, mas também seguros e fáceis de usar. A implementação dessas etapas protegerá seu aplicativo e também aprimorará a experiência geral do usuário. Boa codificação! 🚀🔒👨‍💻

Aikido Security é uma plataforma de segurança de software centrada no desenvolvedor. Ajudamos a manter seu produto seguro, para que você possa focar em escrever código. Você não’ precisa falar com uma equipe de vendas - basta conectar sua conta GitHub, GitLab, Bitbucket ou Azure DevOps para começar a escanear seus repositórios gratuitamente.