O Inspetor de solicitação de webhook é uma ferramenta projetada para analisar a estrutura de requisições de webhook capturadas. Ao colar o método HTTP, os cabeçalhos e o corpo bruto de uma requisição, desenvolvedores de APIs, engenheiros de integração, representantes de suporte técnico e mantenedores de automação podem examinar a formatação dos dados e extrair comandos utilitários para validação local.
Toda a operação de análise ocorre diretamente no navegador do usuário. Os dados colados não são enviados para servidores externos, garantindo que as informações da requisição permaneçam restritas ao ambiente local de execução.
Estrutura e Componentes de uma Requisição de Webhook
As comunicações via webhook dependem de três componentes fundamentais para transferir dados entre sistemas: o método HTTP, os cabeçalhos de metadados e o corpo da mensagem (payload).
O método HTTP define a semântica da ação. Embora a maioria dos webhooks utilize o método POST para enviar novos eventos, sistemas também podem empregar PUT, PATCH, GET ou DELETE.
Os cabeçalhos (headers) transportam informações contextuais cruciais, como o tipo de conteúdo (Content-Type), a identificação do remetente e metadados de segurança. O formato padrão para a entrada de cabeçalhos nesta ferramenta exige uma propriedade por linha, estruturada estritamente como Nome: valor.
O corpo da requisição contém o payload de dados do evento. Para uma inspeção precisa, é fundamental utilizar o corpo bruto exato, exatamente como foi capturado na rede, antes que qualquer parser ou middleware do lado do servidor altere a disposição dos bytes, o espaçamento ou a ordem dos campos.
Formatação de Corpos JSON e URL-Encoded
Os webhooks transmitem dados predominantemente em dois formatos de codificação: JSON (application/json) ou dados de formulário codificados na URL (application/x-www-form-urlencoded). A ferramenta detecta automaticamente esses formatos para apresentar uma visualização estruturada no campo Corpo formatado:
- JSON: O conteúdo é processado internamente por meio de
JSON.parse. Esse processo de análise e reformatação reconstrói a árvore de dados, o que significa que o espaçamento original, recuos e a ordenação exata dos campos presentes no payload bruto serão modificados na exibição formatada. - URL-Encoded: Estruturas de formulários com pares de chave-valor separados por
&e codificados com caracteres especiais são decodificadas e organizadas para facilitar a leitura das variáveis. - Outros formatos: Caso o corpo pertença a outro tipo de especificação, ele será exibido como texto simples, sem alterações. Se a requisição não contiver dados no payload, a ferramenta exibirá a indicação (corpo vazio).
Identificação de Assinaturas e Carimbos de Data/Hora
Para garantir a segurança, muitos provedores de webhook incluem assinaturas criptográficas e carimbos de data/hora (timestamps) nos cabeçalhos das requisições. O inspetor analisa os cabeçalhos fornecidos em busca de padrões de nomes comuns associados a esses mecanismos de segurança, tais como:
signaturehmacdigest- Nomes comuns de carimbos de data/hora (timestamps)
Os campos identificados são listados na seção Campos de assinatura. Se nenhum cabeçalho correspondente a esses padrões for localizado, a ferramenta exibirá a mensagem Nenhuma assinatura comum ou cabeçalho de carimbo de data/hora do webhook foi encontrado..
Distinção entre Inspeção e Verificação Real
É importante destacar que a identificação visual de um cabeçalho de segurança não valida a autenticidade da requisição. A ferramenta apenas aponta a existência do campo.
A verificação real de segurança exige a execução de algoritmos criptográficos específicos (como HMAC-SHA256), o conhecimento da chave secreta compartilhada (secret) fornecida pelo emissor, o tratamento correto da janela de tolerância contra ataques de repetição (replay window) e o acesso aos bytes originais e inalterados do corpo da requisição. A ferramenta não realiza cálculos criptográficos ou validações de integridade.
Testes Locais com cURL
Uma das etapas comuns no desenvolvimento de integrações é reproduzir a requisição recebida em um ambiente de desenvolvimento local. O inspetor facilita esse processo gerando automaticamente um comando utilitário baseado em cURL, configurado com os cabeçalhos e o corpo fornecidos.
O comando gerado é estruturado para apontar de forma fixa para o endereço de testes local:
http://localhost:3000/webhooks
Esse comando utiliza a sintaxe de escape adequada para terminais de linha de comando (shell-quoted), permitindo que o desenvolvedor copie o bloco de texto e execute o teste diretamente em seu terminal para depurar o comportamento do seu endpoint local.
Regras de Validação e Mensagens de Erro
Para garantir a estabilidade do processamento no navegador, a ferramenta aplica limites estritos ao tamanho e à estrutura dos dados inseridos. O descumprimento dessas regras aciona mensagens de erro específicas:
| Cenário de Erro | Mensagem Exibida pelo Sistema |
|---|---|
| Nenhuma informação inserida nos campos de entrada | Cole primeiro pelo menos um cabeçalho ou corpo da solicitação. |
| Volume de cabeçalhos excede o limite de 100.000 caracteres | Os cabeçalhos são muito longos para esta ferramenta. Remova valores não relacionados ou repetidos. |
| Quantidade de linhas de cabeçalho superior a 200 | Existem muitas linhas de cabeçalho. Mantenha a solicitação com 200 cabeçalhos ou menos. |
| Linha de cabeçalho fora do padrão esperado | ‹line›: A linha de cabeçalho é inválida. Usar Nome: valor. |
| Corpo da requisição excede 1.000,000 de caracteres | O corpo é muito longo para esta ferramenta. Mantenha-o abaixo de 1.000.000 de caracteres. |
| Payload com estrutura JSON corrompida ou inválida | O corpo se parece com JSON, mas não pôde ser analisado. |
| Erro de codificação em corpo do tipo formulário | O corpo do formulário contém um escape percentual incompleto. |
Perguntas Frequentes
Esta página pode receber um retorno de chamada de webhook ao vivo?
Não. Cole aqui uma solicitação capturada para inspeção. A página não cria um endpoint público, não recebe retornos de chamada nem envia a solicitação de teste gerada.
Quais formatos de corpo de webhook posso inspecionar?
Corpos de formulários codificados em JSON e URL são detectados e formatados. Outros corpos permanecem como texto simples para que a ferramenta não adivinhe conteúdo XML, multipart ou binário.
Encontrar um campo de assinatura prova que a solicitação é autêntica?
Não. A ferramenta apresenta apenas assinatura e cabeçalhos de carimbo de data/hora relacionados. A verificação real precisa das regras de assinatura exatas do remetente, da chave secreta ou pública e dos bytes de solicitação originais.