Esta página apresenta ferramentas e técnicas para testar integrações de webhooks durante o desenvolvimento e depurar problemas em produção.

​
Desenvolvimento local

​
Expondo servidores locais

Como os webhooks precisam alcançar seu servidor pela internet, você terá que expor publicamente seu servidor de desenvolvimento local.

​
Usando o Cloudflare Tunnels

O Cloudflare Tunnels oferece uma forma gratuita de expor com segurança seu servidor de desenvolvimento local na internet, sem exigir criação de conta nem abertura de portas no firewall: 
# Baixe o cloudflared nas versões (releases) do GitHub ou use um gerenciador de pacotes

# Exponha seu servidor local
cloudflared tunnel --url localhost:3000

# Exemplo de saída:
# Seu Quick Tunnel foi criado! Acesse em (pode levar algum tempo para ficar disponível):
# https://abc123.trycloudflare.com
Use a URL fornecida na configuração do seu webhook: 
{
  "url": "https://abc123.trycloudflare.com/webhook"
}

​
Solução de Problemas Comuns

​
Webhooks não estão chegando

  1. Verifique a acessibilidade da URL – Certifique-se de que seu endpoint está publicamente acessível
  2. Confirme o uso de HTTPS – URLs de webhook devem usar HTTPS
  3. Confira as configurações do firewall – Permita conexões de entrada para a porta do seu webhook
  4. Revise os filtros de eventos – Garanta que você está inscrito nos tipos de evento corretos

​
Falha na verificação de assinatura

  1. Confira a chave secreta – Certifique-se de que está usando a chave correta
  2. Verifique o uso do corpo bruto – Garanta que você está usando o corpo da requisição em formato bruto: 
// ❌ Incorreto – usando o corpo já parseado
const signature = crypto
  .createHmac('sha256', secret)
  .update(JSON.stringify(req.body))
  .digest('hex');

// ✅ Correto – usando o corpo bruto (raw)
app.use('/webhook', express.raw({ type: 'application/json' }));
app.post('/webhook', (req, res) => {
  const signature = crypto
    .createHmac('sha256', secret)
    .update(req.body) // Buffer bruto (raw)
    .digest('hex');
});