Webhook Tester

Um testador de webhooks é um endereço público temporário que regista cada pedido HTTP que lhe é enviado, para que veja exatamente o que um remetente de webhooks realmente entregou. Crie um hook abaixo e obtém um URL único que vive durante 30 minutos: aponte o Stripe, o GitHub, um fornecedor de pagamentos, um serviço de monitorização ou o seu próprio código para ele, acione o evento, e cada entrega chega aqui — método, caminho e consulta, cabeçalhos, corpo e endereço de origem — para inspecionar antes de ligar o processador real.

Última atualização:

O que este serviço guarda — e o que nunca faz

Criar um hook guarda, no servidor de verificação SysOSX, apenas o id do hook, as suas horas de criação e expiração e o endereço que o criou. Cada pedido capturado guarda a hora de chegada, o método, o caminho com a sua cadeia de consulta, os cabeçalhos tal como foram enviados, o corpo até 256 KB (o que exceder é truncado e assinalado) e o endereço do remetente. Um hook guarda no máximo 50 pedidos; as entregas seguintes são recusadas até ele expirar. Tudo é eliminado 30 minutos depois de o hook ser criado, ou imediatamente quando prime o botão de eliminar. O recetor só recebe: nunca vai buscar, seguir ou repetir nada — um pedido capturado não provoca nenhuma chamada de saída. Para a ferramenta de depuração vizinha, veja o traçador de cadeias de estado HTTP, e para o fluxo completo leia depurar webhooks sem a canalização.

Porque é que depurar webhooks é incómodo sem um recetor

Um webhook é o servidor de outra pessoa a chamar o seu, segundo o horário dela, em resposta a um evento que não controla — um pagamento concluído, um push a chegar, um alerta a disparar. Essa forma é o que torna os webhooks penosos de depurar. O remetente não consegue chegar ao seu portátil, por isso o desenvolvimento local precisa de um túnel ou de uma máquina pública de staging antes de ver uma única entrega real; o evento pode ser difícil de acionar duas vezes, por isso a única entrega que conseguir é melhor que seja capturada por completo; e quando algo falha, o painel do remetente costuma mostrar apenas o código de estado que o seu endpoint devolveu, e não o que ele realmente enviou. O cabeçalho de assinatura estava presente? O corpo era a forma JSON que a documentação prometia, ou vinha codificado como formulário? A nova tentativa enviou o mesmo id de evento? Nenhuma destas perguntas pode ser respondida apenas com os registos do seu processador se este rejeitou o pedido antes de o registar — que é exatamente o que acontece com os erros de assinatura e de análise que dominam a depuração de webhooks.

Um recetor temporário retira a canalização desse ciclo. Em vez de implementar um processador meio escrito só para ver o que chega, cria um endereço que aceita tudo, regista fielmente e lhe mostra: os cabeçalhos pela ordem e com a capitalização com que chegaram, o corpo bruto antes de qualquer analisador ter oportunidade de o rejeitar, a cadeia de consulta onde os remetentes por vezes escondem parâmetros, e o método exato — porque alguns fornecedores entregam com POST, outros com PUT, e alguns poucos verificam o estado com GET. Com uma entrega real capturada no ecrã, pode escrever o seu processador contra a verdade em vez de contra a documentação, construir um fixture para os seus testes a partir da carga real e comparar lado a lado uma nova tentativa falhada com o original. Depois elimina o hook, aponta o fornecedor para o seu endpoint real e aciona o evento mais uma vez para ver o seu próprio processador responder-lhe. Trinta minutos é deliberadamente curto: tempo suficiente para uma sessão de depuração, e curto o bastante para que um endereço de teste esquecido e cheio de cargas capturadas não fique pela internet.

Perguntas frequentes

Quanto tempo vive um hook e quanto pode capturar?

Um hook vive 30 minutos a partir do momento em que o cria; depois, o hook e tudo o que capturou são eliminados automaticamente. Guarda até 50 pedidos; as entregas além disso são recusadas com uma resposta 429 até o hook expirar. Cada corpo é guardado até 256 KB — um corpo mais longo é truncado e a captura é assinalada como truncada, para que saiba que não está a ver tudo.

Quem pode ver o que o meu hook captura?

Qualquer pessoa que tenha o URL do hook. O id no URL é a única credencial: autoriza enviar pedidos e ler as capturas, sem conta nem palavra-passe por cima. É isso que torna a ferramenta instantânea de usar, e é por isso que deve tratar o URL como uma palavra-passe — não o publique e nunca aponte tráfego de produção com segredos ou dados pessoais para um visualizador partilhado como este.

O recetor responde ao remetente, segue ligações ou repete pedidos?

Não. O recetor responde a cada entrega aceite com uma pequena confirmação JSON 200 de que chegou, e não faz mais nada com ela: nunca vai buscar URL encontrados numa carga, nunca segue redirecionamentos e não oferece repetição nem reencaminhamento. Receber e inspecionar é todo o serviço, o que impede que uma carga capturada se transforme em tráfego de saída.

Que remetentes posso testar com isto?

Tudo o que consiga enviar um pedido HTTP para um URL público: Stripe, GitHub, Shopify, fornecedores de pagamentos e formulários, serviços de monitorização e CI, um dispositivo IoT, ou o seu próprio código com curl. Crie o hook, cole o URL nas definições de webhook do fornecedor (ou no seu script), acione o evento e veja a entrega chegar aqui em segundos. Lembre-se de remover o URL de teste do fornecedor depois, ou de o apontar para o seu processador real.