Posso testar um webhook sem expor minha máquina local?

Sim — esse é o objetivo de um receiver mock. O provedor chama um URL público que não é seu laptop, para que você possa capturar e ler entregas sem um túnel e sem abrir uma porta.

Verei os cabeçalhos de assinatura que o provedor envia?

Sim. O inspetor registra os cabeçalhos de cada entrega, incluindo cabeçalhos de assinatura do provedor como Stripe-Signature e X-Hub-Signature-256. Cabeçalhos de credenciais como Authorization, Cookie e X-Api-Key são armazenados redigidos, e apenas o primeiro valor de um cabeçalho repetido é mantido. Verificar uma assinatura continua sendo trabalho do seu handler — o mock aceita o que quer que chegue.

O endpoint pode responder com um valor retirado da requisição?

Sim. Os tokens de requisição permitem que a resposta ecoe parte do corpo de entrada, que é o que handshakes como o url_verification do Slack exigem antes de ativarem um endpoint.

Testar um receptor de webhook

Receba chamadas de webhook recebidas e inspecione seus cabeçalhos e corpo em tempo real.

Para testar um receptor de webhook você precisa de uma URL pública que o remetente possa de fato alcançar, o que exclui o localhost. Um endpoint mock de webhook lhe dá essa URL imediatamente: ele aceita o POST, retorna a confirmação que o provedor espera e registra a requisição completa para que você possa ler os cabeçalhos e o corpo que o remetente realmente transmitiu — ao contrário dos que a documentação diz transmitir.

Por que o provedor não pode simplesmente chamar o localhost?

Um webhook é o servidor do provedor chamando o seu. http://localhost:3000 significa "esta máquina" do lado do provedor também, então a chamada nunca sai da rede deles. Ferramentas de túneis resolvem isso expondo seu laptop; um endpoint mock resolve isso retirando seu laptop completamente do processo.

Essa diferença importa no início. Antes que o seu handler (manipulador) exista, o que você realmente precisa saber é o que o provedor envia — quais cabeçalhos, qual corpo, qual tipo de conteúdo. Um mock responde a essa pergunta com apenas um envio, e você escreve o handler em relação à requisição gravada em vez do exemplo da documentação.

O que o endpoint deve responder ao remetente?

Quase todo provedor trata qualquer 2xx como sucesso e todo o resto como falha que vale tentar de novo, então retorne 200 rapidamente e mantenha o corpo pequeno. O Stripe tenta novamente por dias em caso de não-2xx; o GitHub registra a falha no log de entrega. Ambos punem um handler lento com a mesma severidade que um quebrado.

Alguns provedores exigem mais do que um código de status. A API de Eventos do Slack não habilitará um endpoint até que ele retorne em eco o valor do challenge da requisição de verificação. Se o seu endpoint tem que responder com algo derivado da requisição, crie um mock desse eco em vez de um corpo fixo.

Como você vê o que o remetente realmente enviou?

Abra o inspetor para o mock e cada entrega será listada com seu método, cabeçalhos, corpo e carimbo de data/hora. Esta é a parte difícil de obter de outra forma: cabeçalhos de assinatura, o tipo de conteúdo exato e a diferença entre o que o provedor documenta e o que ele transmite.

Acione um evento real do painel do provedor em vez de enviar a si mesmo um POST escrito à mão. Um payload que você mesmo escreveu confirma suas suposições; um payload que o provedor enviou as corrige.

Vale a pena comparar lado a lado duas entregas do mesmo evento. Os provedores fazem novas entregas após uma falha, e a tentativa de repetição nem sempre é idêntica em bytes à primeira tentativa — se o provedor envia um cabeçalho de ID de entrega, é a partir dele que sua chave de idempotência deve ser criada, não de um hash do corpo.

O que geralmente dá errado?

Testar com um payload que você inventou. Isso prova que seu parser lida com seu próprio JSON, o que nunca esteve em dúvida.
Retornar 200 antes do trabalho ser concluído — ou depois. Reconheça rapidamente e processe de forma assíncrona. Os provedores atingem o tempo limite muito antes que um handler lento termine.
Ignorar novas entregas. Repetições significam que o mesmo evento chega duas vezes. Os handlers devem ser idempotentes, e enviar a mesma entrega duas vezes é como você prova isso.
Assumir que o mock verifica assinaturas. Ele não faz isso. A verificação da assinatura é trabalho do seu handler e precisa ser testada contra o remetente real.

Quando usar isso

Integrar um webhook de terceiros (Stripe, GitHub, um provedor de pagamento) significa que você precisa de uma URL para apontá-lo — e de uma forma de ver exatamente o que ele envia. Crie um mock POST, forneça a URL ao provedor e observe cada chamada chegar no inspetor de requisições ao vivo: método, cabeçalhos, query e corpo.

Criar o mock

curl -X POST https://quickmock.dev/api/mocks \
  -H 'Content-Type: application/json' \
  -d '{
  "method": "POST",
  "response_status": 200,
  "response_body": "{\"received\":true}"
}'

Chamá-lo

curl -X POST -H 'Content-Type: application/json' -d '{"event":"payment.succeeded"}' https://quickmock.dev/m/<slug>

Abra a página do mock e cole seu token de administrador para observar o método recebido, cabeçalhos, query e corpo no inspetor ao vivo privado.

O que você obtém

{"received":true}

FAQ

Posso testar um webhook sem expor minha máquina local?: Sim — esse é o objetivo de um receiver mock. O provedor chama um URL público que não é seu laptop, para que você possa capturar e ler entregas sem um túnel e sem abrir uma porta.
Verei os cabeçalhos de assinatura que o provedor envia?: Sim. O inspetor registra os cabeçalhos de cada entrega, incluindo cabeçalhos de assinatura do provedor como Stripe-Signature e X-Hub-Signature-256. Cabeçalhos de credenciais como Authorization, Cookie e X-Api-Key são armazenados redigidos, e apenas o primeiro valor de um cabeçalho repetido é mantido. Verificar uma assinatura continua sendo trabalho do seu handler — o mock aceita o que quer que chegue.
O endpoint pode responder com um valor retirado da requisição?: Sim. Os tokens de requisição permitem que a resposta ecoe parte do corpo de entrada, que é o que handshakes como o url_verification do Slack exigem antes de ativarem um endpoint.

Construa o seu próprio

Criar um mock

Templates prontos para isso: Simular um payload de webhook do Stripe, Simular um webhook de pedido do Shopify, Simular um webhook de push do GitHub

Guias relacionados

← Todos os guias

Última atualização: 2026-10-17