Déboguer les webhooks sans déploiement : une boîte de réception temporaire que vous pouvez ouvrir en 10 secondes

Vous voulez voir ce que Stripe envoie lorsqu'un paiement réussit. Ou ce que GitHub envoie lorsque quelqu'un ouvre une pull request. L'approche standard : démarrer un serveur local, installer ngrok, configurer un tunnel, garder une fenêtre de terminal ouverte, espérer la session n'expire pas à mi-test. Ou pire : déployez un gestionnaire à moitié terminé pour effectuer la préparation et suivre les journaux pendant que vous attendez.

Les deux workflows font perdre du temps sur l'infrastructure alors que la vraie question est simple : *à quoi ressemble la charge utile ?*

La boîte de réception des webhooks de Botoi vous donne une URL jetable qui capture les charges utiles entrantes et les stocke pendant 24 heures. Trois appels API. Pas de comptes, pas de tunnels, pas de serveurs.

Le flux de travail en 3 étapes

1. Créer une boîte de réception pour obtenir une URL de réception unique
2. Pointez la source de votre webhook à cette URL
3. Lister les charges utiles pour inspecter ce qui est arrivé

Chaque étape est une seule curl commande.

Étape 1 : Créer une boîte de réception

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

Réponse:

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

Enregistrez le inbox_id et url valeurs. La boîte de réception dure 24 heures (86 400 secondes), puis l'URL et toutes les charges utiles stockées sont supprimées.

Étape 2 : Envoyer un webhook dans la boîte de réception

Dirigez votre fournisseur de webhook vers le url à partir de l'étape 1. La boîte de réception accepte n'importe quel corps 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"
  }'

Réponse:

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

Étape 3 : Inspecter les charges utiles

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

Réponse:

{
  "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
  }
}

Chaque charge utile est stockée avec un horodatage et un identifiant unique. Vous pouvez appeler le point de terminaison de la liste autant de fois que vous le souhaitez dans la fenêtre de 24 heures.

Exemple concret : débogage d'un webhook Stripe

Le mode test de Stripe vous permet de déclencher des événements depuis le tableau de bord. Au lieu de mettre en place un serveur pour les recevoir, pointez Stripe vers l’URL de votre boîte de réception.

1. Créez la boîte de réception

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. Ajoutez l'URL à Stripe

Aller à Tableau de bord Stripe > Développeurs > Webhooks. Cliquez sur "Ajouter un point de terminaison" et collez le INBOX_URL. Sélectionnez les événements qui vous intéressent, comme payment_intent.succeeded et invoice.payment_failed.

3. Déclenchez un événement de test

Cliquez sur « Envoyer le webhook de test » dans le tableau de bord Stripe. Inspectez ensuite ce qui est arrivé :

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

Vous disposez désormais de la charge utile exacte envoyée par Stripe, avec tous les objets imbriqués, noms de champs et types. Utilisez-le pour écrire votre gestionnaire en toute confiance au lieu de deviner le schéma.

Exemple concret : tester une intégration de webhook GitHub

Les webhooks du référentiel GitHub se déclenchent lors d'événements tels que push, pull_request, et issues. Voici comment en capturer un sans exécuter de code localement.

1. Créez une boîte de réception et configurez 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. Ouvrez une pull request, puis vérifiez la boîte de réception

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}'

Sortie (exemple) :

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

Vous pouvez voir la structure exacte envoyée par GitHub, y compris des champs comme action, sender, repository, et le plein pull_request objet. C'est plus rapide que de lire la documentation de GitHub et de deviner quels champs sont renseignés pour chaque type d'événement.

L'automatiser : un script de test

Ce script bash crée une boîte de réception, envoie une charge utile de test, la récupère et vérifie l'aller-retour. Enregistrez-le sous test-webhook.sh et exécutez-le pour confirmer que votre intégration fonctionne de bout en bout.

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

Résultat attendu :

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}
  ]
}

Comparaison : boîte de réception botoi et alternatives

Fonctionnalité	Boîte de réception Botoi	ngrok	webhook.site	RequêteBin
Temps d'installation	Une commande curl	Installer CLI + authentification	Ouvrir le navigateur	Ouvrir le navigateur
Serveur local requis	Non	Oui	Non	Non
Compte requis	Non	Oui (niveau gratuit)	Non (limité)	Oui
Accès programmatique	API complète	API (payante)	API (payante)	API (payante)
Compatible CI/CD	Oui; boucle + jq	Possible; complexe	Non	Non
Durée de vie	24 heures	Basé sur la session	Varie	48 heures
Le processus reste en cours	Non	Oui	Non	Non
Gratuite	Oui	Limitée	Limitée	Non

Le principal avantage de la boîte de réception botoi est que tout se passe via l'API. Vous pouvez créer des boîtes de réception, envoyer des tests charges utiles et récupérez les résultats dans les scripts shell, les pipelines CI et les tests d'intégration sans ouvrir de navigateur ou maintenir un processus en arrière-plan en vie.

Quand l'utiliser

• Explorer un nouveau fournisseur de webhooks. Avant d'écrire le code du gestionnaire, capturez les charges utiles réelles pour comprendre la forme des données, les noms de champs et les cas extrêmes.
• Tests d'intégration en CI. Ouvrez une boîte de réception dans votre suite de tests, déclenchez le webhook, interrogez la liste point final et affirmer le contenu de la charge utile.
• Débogage d'un gestionnaire cassé. Remplacez temporairement l'URL de votre webhook de production par une URL de boîte de réception pour capturer la charge utile exacte à l’origine des échecs.
• Programmation en binôme ou démos. Partagez l'ID de la boîte de réception avec un coéquipier. Vous pouvez tous les deux envoyer des charges utiles et inspecter les résultats de différentes machines.

La boîte de réception est jetable de par sa conception. Créez-en un lorsque vous en avez besoin, utilisez-le pour la session et laissez-le expirer. Pas de nettoyage, pas de points de terminaison persistants, pas de surprises de facturation.