Estrutura e Funcionamento de uma Solicitação de Webhook
Os webhooks são mecanismos de comunicação essenciais para a integração de sistemas modernos, permitindo que uma aplicação envie dados em tempo real para outra assim que ocorre um evento específico. No entanto, diagnosticar problemas em integrações de webhooks pode ser complexo, uma vez que estas comunicações ocorrem de forma assíncrona entre servidores.
Para analisar e depurar estas comunicações, é necessário inspecionar a estrutura exata da solicitação capturada. Uma solicitação de webhook é composta por três elementos fundamentais: o método HTTP, os cabeçalhos (headers) e o corpo (body). Compreender a disposição destes elementos ajuda programadores de APIs, engenheiros de integração, representantes de suporte técnico e mantenedores de automações a identificar falhas de formatação ou de autenticação.
O processamento e a análise dos dados colados nesta ferramenta ocorrem inteiramente no navegador do utilizador. A plataforma BroBroGo não carrega nem guarda qualquer informação submetida, garantindo que os dados da sua solicitação permanecem estritamente locais durante a inspeção.
Parâmetros de Entrada e Limites de Validação
Para inspecionar uma solicitação, deve introduzir os dados capturados respeitando as seguintes especificações e limites técnicos do utilitário:
- Método: Selecionado a partir de uma lista predefinida que inclui os métodos HTTP comuns para envio de webhooks:
POST,PUT,PATCH,GETeDELETE. - Cabeçalhos: Devem ser inseridos com um cabeçalho por linha, utilizando estritamente o formato
Nome: valor. O limite máximo permitido é de 200 linhas de cabeçalho não vazias, com um comprimento total que não pode exceder 100.000 caracteres. - Corpo: Deve conter o corpo bruto exato capturado antes de qualquer análise ou processamento do lado do servidor. O limite máximo para o corpo é de 1.000.000 de caracteres.
Mensagens de Erro de Validação
Se os dados inseridos violarem as regras de formatação ou os limites de tamanho, a ferramenta exibirá uma das seguintes mensagens de erro específicas:
- Se tentar submeter o formulário sem dados: "Cole primeiro pelo menos um cabeçalho ou corpo da solicitação."
- Se o comprimento dos cabeçalhos ultrapassar o limite: "Os cabeçalhos são muito longos para esta ferramenta. Remova valores não relacionados ou repetidos."
- Se o número de linhas de cabeçalho exceder 200: "Existem muitas linhas de cabeçalho. Mantenha a solicitação com 200 cabeçalhos ou menos."
- Se uma linha de cabeçalho não respeitar a estrutura correta: "
‹line›: A linha de cabeçalho é inválida. Usar Nome: valor." - Se o corpo ultrapassar o limite de tamanho: "O corpo é muito longo para esta ferramenta. Mantenha-o abaixo de 1.000.000 de caracteres."
- Se o corpo JSON contiver erros estruturais: "O corpo se parece com JSON, mas não pôde ser analisado."
- Se o corpo codificado em URL contiver erros de codificação: "O corpo do formulário contém um escape percentual incompleto."
Formatação do Corpo e Tratamento de Dados
O comportamento do inspetor varia consoante o formato do corpo detetado na solicitação:
| Formato Detetado | Comportamento de Formatação e Processamento |
|---|---|
| JSON | O corpo é analisado através da função JSON.parse. Durante este processo, o JSON é formatado para facilitar a leitura, o que significa que o espaçamento original e a ordenação dos campos são perdidos. |
| URL-encoded | Os dados de formulário codificados em URL são identificados, descodificados e estruturados de forma legível. |
| Outros Formatos | Corpos que não correspondam a JSON ou a dados de formulário codificados em URL são tratados como texto simples, mantendo a sua disposição original sem alterações. |
| Corpo Vazio | Se nenhum corpo for fornecido, a ferramenta exibe a indicação "(corpo vazio)". |
A preservação do conteúdo bruto do corpo é de extrema importância para o processamento de webhooks, uma vez que qualquer alteração nos bytes originais (incluindo espaços em branco e quebras de linha) invalidará as verificações de assinaturas criptográficas realizadas pelos servidores de destino.
Identificação de Assinaturas e Carimbos de Data/Hora
Muitos fornecedores de webhooks incluem cabeçalhos de segurança para mitigar ataques de repetição e garantir a integridade da mensagem. O inspetor analisa os cabeçalhos fornecidos à procura de padrões de nomes comuns associados a assinaturas e carimbos de data/hora (timestamps), tais como signature, hmac, digest e termos relacionados com marcas temporais.
Se nenhum cabeçalho correspondente a estes padrões for identificado, a ferramenta apresentará 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
É fundamental compreender a diferença entre identificar a presença de um campo de assinatura e verificar a autenticidade da solicitação. A ferramenta limita-se a detetar e listar os campos de assinatura encontrados. Ela não calcula HMAC, não executa algoritmos criptográficos, não valida os bytes originais do payload, não gere segredos ou chaves, não verifica janelas de tolerância a repetições (replay windows) nem realiza validações específicas de fornecedores.
Como alerta a interface: "Encontrar um campo de assinatura não prova que o pedido é autêntico — a verificação real exige as regras de assinatura do remetente, o segredo ou chave, e os bytes originais do pedido.".
Geração de Comandos cURL para Testes Locais
Para apoiar o desenvolvimento e a depuração local, a ferramenta gera automaticamente um comando cURL formatado para a consola (shell). Este comando é configurado de forma fixa para apontar para o endereço de desenvolvimento local http://localhost:3000/webhooks.
Ao copiar este comando cURL gerado, pode simular o envio do webhook diretamente para o seu ambiente de execução local, preservando os cabeçalhos e a estrutura do corpo que acabou de inspecionar. Isto elimina a necessidade de configurar manualmente ferramentas de terceiros ou de aguardar que o serviço externo envie um novo evento real durante a fase de testes.
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.