Depurar webhooks sin implementarlos: una bandeja de entrada temporal que puedes activar en 10 segundos

Quiere ver qué envía Stripe cuando se realiza un pago. O lo que envía GitHub cuando alguien abre una solicitud de extracción. El enfoque estándar: iniciar un servidor local, instalar ngrok, configurar un túnel, mantener abierta una ventana de terminal, esperar la sesión no caduca a mitad de la prueba. O peor: despliegue un controlador a medio terminar en el escenario y siga los registros mientras espera.

Ambos flujos de trabajo desperdician tiempo en infraestructura cuando la verdadera pregunta es simple: *¿cómo es la carga útil?*

La bandeja de entrada del webhook de Botoi le brinda una URL desechable que captura las cargas útiles entrantes y las almacena durante 24 horas. Tres llamadas API. Sin cuentas, sin túneles, sin servidores.

El flujo de trabajo de 3 pasos

1. Crear una bandeja de entrada para obtener una URL de recepción única
2. Señale la fuente de su webhook en esa URL
3. Listar las cargas útiles para inspeccionar lo que llegó

Cada paso es un solo curl dominio.

Paso 1: crea una bandeja de entrada

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

Respuesta:

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

guardar el inbox_id y url valores. La bandeja de entrada dura 24 horas (86.400 segundos), luego la URL y todas las cargas útiles almacenadas se eliminan.

Paso 2: envía un webhook a la bandeja de entrada

Dirija su proveedor de webhook a la url desde el paso 1. La bandeja de entrada acepta cualquier cuerpo 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"
  }'

Respuesta:

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

Paso 3: inspeccionar las cargas útiles

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

Respuesta:

{
  "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 se almacena con una marca de tiempo y una identificación única. Puede llamar al punto final de la lista tantas veces como desee dentro de la ventana de 24 horas.

Ejemplo del mundo real: depurar un webhook de Stripe

El modo de prueba de Stripe te permite activar eventos desde el panel. En lugar de levantar un servidor para recibirlos, apunte Stripe a la URL de su bandeja de entrada.

1. Crea la bandeja 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. Agrega la URL a Stripe

Ir a Panel de control de Stripe > Desarrolladores > Webhooks. Haga clic en "Agregar punto final" y pegue el INBOX_URL. Seleccione los eventos que le interesan, me gusta payment_intent.succeeded y invoice.payment_failed.

3. Activar un evento de prueba

Haga clic en "Enviar webhook de prueba" en el panel de Stripe. Luego inspecciona lo que llegó:

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

Ahora tiene la carga útil exacta que envía Stripe, con todos los objetos anidados, nombres de campos y tipos. Utilice esto para escribir su controlador con confianza en lugar de adivinar el esquema.

Ejemplo del mundo real: probar una integración de webhook de GitHub

Los webhooks del repositorio de GitHub se activan en eventos como push, pull_request, y issues. A continuación se explica cómo capturar uno sin ejecutar ningún código localmente.

1. Crea una bandeja de entrada y configura 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 una solicitud de extracción y luego revise la bandeja 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}'

Salida (ejemplo):

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

Puedes ver la estructura exacta que envía GitHub, incluidos campos como action, sender, repository, y el completo pull_request objeto. Esto es más rápido que leer los documentos de GitHub y adivinar qué campos se completan para cada tipo de evento.

Automatizándolo: un script de prueba

Este script bash crea una bandeja de entrada, envía una carga útil de prueba, la recupera y verifica el viaje de ida y vuelta. Guárdalo como test-webhook.sh y ejecútelo para confirmar que su integración funciona de principio a fin.

#!/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}
  ]
}

Comparación: bandeja de entrada de botoi vs. las alternativas

Característica	Bandeja de entrada de Botoi	ngrok	webhook.site	SolicitudBin
tiempo de configuración	Un comando curl	Instalar CLI + autenticación	Abrir navegador	Abrir navegador
Se requiere servidor local	No	Sí	No	No
Cuenta requerida	No	Sí (nivel gratuito)	No (limitado)	Sí
Acceso programático	API completa	API (pago)	API (pago)	API (pago)
Compatible con CI/CD	Sí; rizo + jq	Posible; complejo	No	No
TTL	24 horas	Basado en sesiones	Varía	48 horas
El proceso sigue funcionando	No	Sí	No	No
Gratis	Sí	Limitada	Limitada	No

La principal ventaja de la bandeja de entrada de botoi es que todo sucede a través de la API. Puedes crear bandejas de entrada, enviar prueba. cargas útiles y recuperar resultados dentro de scripts de shell, canalizaciones de CI y pruebas de integración sin abrir un navegador o mantener vivo un proceso en segundo plano.

Cuando usar esto

• Explorando un nuevo proveedor de webhooks. Antes de escribir el código del controlador, capture cargas útiles reales para comprenderlas la forma de los datos, los nombres de los campos y los casos extremos.
• Pruebas de integración en CI. Abra una bandeja de entrada en su conjunto de pruebas, active el webhook, sondee la lista punto final y afirmar el contenido de la carga útil.
• Depurando un controlador roto. Cambie temporalmente la URL de su webhook de producción por una URL de bandeja de entrada para capturar la carga útil exacta que causa fallas.
• Programación en pareja o demostraciones. Comparte el ID de la bandeja de entrada con un compañero de equipo. Ambos pueden enviar cargas útiles y inspeccionar los resultados de diferentes máquinas.

La bandeja de entrada es desechable por diseño. Cree uno cuando lo necesite, úselo para la sesión y déjelo caducar. Sin limpieza, sin puntos finales persistentes, sin sorpresas en la facturación.