Depure webhooks sem implantar: uma caixa de entrada temporária que você pode ativar em 10 segundos

Você deseja ver o que o Stripe envia quando um pagamento é bem-sucedido. Ou o que o GitHub envia quando alguém abre uma solicitação pull. A abordagem padrão: iniciar um servidor local, instalar o ngrok, configurar um túnel, manter uma janela de terminal aberta, esperar que a sessão não expira no meio do teste. Ou pior: implante um manipulador incompleto nos logs de teste e finalização enquanto você espera.

Ambos os fluxos de trabalho perdem tempo com infraestrutura quando a verdadeira questão é simples: *como é a carga útil?*

A caixa de entrada do webhook do Botoi fornece uma URL descartável que captura as cargas recebidas e as armazena por 24 horas. Três chamadas de API. Sem contas, sem túneis, sem servidores.

O fluxo de trabalho em três etapas

1. Crie uma caixa de entrada para obter um URL de recebimento exclusivo
2. Aponte a fonte do seu webhook naquele URL
3. Liste as cargas úteis para inspecionar o que chegou

Cada passo é um único curl comando.

Etapa 1: crie uma caixa de entrada

curl -X POST https://api.botoi.com/v1/webhook/inbox/create

Resposta:

{
  "success": true,
  "data": {
    "inbox_id": "a1b2c3d4",
    "url": "https://api.botoi.com/v1/webhook/inbox/a1b2c3d4/receive",
    "expires_in": 86400
  }
}

Salve o inbox_id e url valores. A caixa de entrada dura 24 horas (86.400 segundos), depois o URL e todas as cargas armazenadas são excluídas.

Etapa 2: envie um webhook para a caixa de entrada

Aponte seu provedor de webhook para o url da etapa 1. A caixa de entrada aceita qualquer corpo JSON:

curl -X POST https://api.botoi.com/v1/webhook/inbox/a1b2c3d4/receive \\
  -H "Content-Type: application/json" \\
  -d '{
    "event": "payment_intent.succeeded",
    "amount": 4999,
    "currency": "usd",
    "customer_email": "buyer@example.com"
  }'

Resposta:

{
  "success": true,
  "data": {
    "received": true,
    "payload_id": "e5f6g7h8"
  }
}

Etapa 3: inspecionar as cargas

curl -X POST https://api.botoi.com/v1/webhook/inbox/a1b2c3d4/list

Resposta:

{
  "success": true,
  "data": {
    "inbox_id": "a1b2c3d4",
    "payloads": [
      {
        "id": "e5f6g7h8",
        "received_at": "2026-03-26T10:00:00Z",
        "body": {
          "event": "payment_intent.succeeded",
          "amount": 4999,
          "currency": "usd",
          "customer_email": "buyer@example.com"
        }
      }
    ],
    "count": 1
  }
}

Cada carga útil é armazenada com um carimbo de data/hora e um ID exclusivo. Você pode chamar o endpoint da lista quantas vezes quiser dentro da janela de 24 horas.

Exemplo do mundo real: depurando um webhook Stripe

O modo de teste do Stripe permite acionar eventos no painel. Em vez de montar um servidor para recebê-los, aponte Stripe para o URL da sua caixa de entrada.

1. Crie a caixa de entrada

INBOX=\$(curl -s -X POST https://api.botoi.com/v1/webhook/inbox/create)
INBOX_ID=\$(echo \$INBOX | jq -r '.data.inbox_id')
INBOX_URL=\$(echo \$INBOX | jq -r '.data.url')
echo "Inbox URL: \$INBOX_URL"

2. Adicione o URL ao Stripe

Vá para Stripe Dashboard > Desenvolvedores > Webhooks. Clique em "Adicionar endpoint" e cole o INBOX_URL. Selecione os eventos de seu interesse, gosto payment_intent.succeeded e invoice.payment_failed.

3. Acione um evento de teste

Clique em “Enviar webhook de teste” no painel do Stripe. Em seguida, inspecione o que chegou:

curl -s -X POST "https://api.botoi.com/v1/webhook/inbox/\$INBOX_ID/list" | jq '.data.payloads'

Agora você tem a carga exata que o Stripe envia, com todos os objetos aninhados, nomes de campos e tipos. Use isso para escrever seu manipulador com confiança, em vez de adivinhar o esquema.

Exemplo do mundo real: testando uma integração de webhook do GitHub

Os webhooks do repositório GitHub são acionados em eventos como push, pull_request, e issues. Veja como capturar um sem executar nenhum código localmente.

1. Crie uma caixa de entrada e configure o GitHub

# Create the inbox
INBOX=\$(curl -s -X POST https://api.botoi.com/v1/webhook/inbox/create)
INBOX_URL=\$(echo \$INBOX | jq -r '.data.url')
INBOX_ID=\$(echo \$INBOX | jq -r '.data.inbox_id')

# Add webhook to your repo via GitHub API
curl -X POST \\
  -H "Authorization: token \$GITHUB_TOKEN" \\
  -H "Content-Type: application/json" \\
  "https://api.github.com/repos/your-org/your-repo/hooks" \\
  -d "{
    \\"config\\": {
      \\"url\\": \\"\$INBOX_URL\\",
      \\"content_type\\": \\"json\\"
    },
    \\"events\\": [\\"pull_request\\"]
  }"

2. Abra uma solicitação pull e verifique a caixa de entrada

curl -s -X POST "https://api.botoi.com/v1/webhook/inbox/\$INBOX_ID/list" \\
  | jq '.data.payloads[0].body | {action, number: .pull_request.number, title: .pull_request.title}'

Saída (exemplo):

{
  "action": "opened",
  "number": 42,
  "title": "Add rate limiting to /api/orders"
}

Você pode ver a estrutura exata que o GitHub envia, incluindo campos como action, sender, repository, e o completo pull_request objeto. Isso é mais rápido do que ler os documentos do GitHub e adivinhar quais campos são preenchidos para cada tipo de evento.

Automatizando: um script de teste

Este script bash cria uma caixa de entrada, envia uma carga de teste, recupera-a e verifica a viagem de ida e volta. Salve como test-webhook.sh e execute-o para confirmar se sua integração funciona de ponta a ponta.

#!/bin/bash
set -euo pipefail

API="https://api.botoi.com/v1/webhook/inbox"

echo "Creating inbox..."
INBOX=\$(curl -s -X POST "\$API/create")
INBOX_ID=\$(echo "\$INBOX" | jq -r '.data.inbox_id')
INBOX_URL=\$(echo "\$INBOX" | jq -r '.data.url')
echo "Inbox ID: \$INBOX_ID"
echo "Receive URL: \$INBOX_URL"

echo ""
echo "Sending test payload..."
SEND=\$(curl -s -X POST "\$INBOX_URL" \\
  -H "Content-Type: application/json" \\
  -d '{
    "event": "order.created",
    "order_id": "ord_98765",
    "total": 129.99,
    "items": [
      {"sku": "WIDGET-A", "qty": 2},
      {"sku": "GADGET-B", "qty": 1}
    ]
  }')

PAYLOAD_ID=\$(echo "\$SEND" | jq -r '.data.payload_id')
echo "Payload ID: \$PAYLOAD_ID"

echo ""
echo "Retrieving payloads..."
LIST=\$(curl -s -X POST "\$API/\$INBOX_ID/list")
COUNT=\$(echo "\$LIST" | jq -r '.data.count')

if [ "\$COUNT" -ge 1 ]; then
  echo "Success: \$COUNT payload(s) received"
  echo "\$LIST" | jq '.data.payloads[0].body'
else
  echo "Error: no payloads found"
  exit 1
fi

Resultado esperado:

Creating inbox...
Inbox ID: a1b2c3d4
Receive URL: https://api.botoi.com/v1/webhook/inbox/a1b2c3d4/receive

Sending test payload...
Payload ID: e5f6g7h8

Retrieving payloads...
Success: 1 payload(s) received
{
  "event": "order.created",
  "order_id": "ord_98765",
  "total": 129.99,
  "items": [
    {"sku": "WIDGET-A", "qty": 2},
    {"sku": "GADGET-B", "qty": 1}
  ]
}

Comparação: caixa de entrada do botoi vs. as alternativas

Recurso	Caixa de entrada do Botoi	ngrok	webhook.site	SolicitarBin
Tempo de configuração	Um comando curl	Instale CLI + autenticação	Abra o navegador	Abra o navegador
Servidor local necessário	Não	Sim	Não	Não
Conta necessária	Não	Sim (nível gratuito)	Não (limitado)	Sim
Acesso programático	API completa	API (paga)	API (paga)	API (paga)
Compatível com CI/CD	Sim; enrolar + jq	Possível; complexo	Não	Não
TTL	24 horas	Baseado em sessão	Varia	48 horas
O processo continua em execução	Não	Sim	Não	Não
Livre	Sim	Limitada	Limitada	Não

A principal vantagem do inbox do botoi é que tudo acontece através da API. Você pode criar caixas de entrada, enviar testes cargas úteis e recuperar resultados dentro de scripts de shell, pipelines de CI e testes de integração sem abrir um navegador ou manter ativo um processo em segundo plano.

Quando usar isso

• Explorando um novo provedor de webhook. Antes de escrever o código do manipulador, capture cargas reais para entender o formato dos dados, nomes de campos e casos extremos.
• Testes de integração em CI. Crie uma caixa de entrada em seu conjunto de testes, acione o webhook, pesquise a lista endpoint e afirme o conteúdo da carga útil.
• Depurando um manipulador quebrado. Troque temporariamente o URL do webhook de produção por um URL da caixa de entrada para capturar a carga exata que causa falhas.
• Programação em pares ou demonstrações. Compartilhe o ID da caixa de entrada com um colega de equipe. Vocês dois podem enviar cargas úteis e inspecionar os resultados de diferentes máquinas.

A caixa de entrada é descartável por design. Crie um quando precisar, use-o na sessão e deixe-o expirar. Sem limpeza, sem endpoints persistentes, sem surpresas de faturamento.