テスト

Webhook のテストとデバッグ

本番環境にデプロイする前に、webhook 連携が正しく動作することを確認してください。このページでは、ローカル環境で webhook を受信する方法と、配信や確認でよくある失敗の原因を特定する方法について説明します。

​

ローカル開発

Webhook には公開アクセス可能な URL が必要なため、開発中はローカルサーバーをインターネットに公開する必要があります。

​

Cloudflare Tunnels の利用

Cloudflare Tunnels は、ファイアウォールのポートを開放することなくローカルサーバーを公開できる無料の手段です。

cloudflared tunnel --url localhost:3000

https://abc123.trycloudflare.com のような公開 URL が発行されます。この URL を Webhook の設定で使用してください：

{
  "url": "https://abc123.trycloudflare.com/webhook"
}

​

トラブルシューティング

​

Webhook が届かない

• エンドポイントにアクセスできない - サーバーがインターネットから到達可能であり、ファイアウォールが受信接続を許可していることを確認してください
• HTTP を使用している - Webhook の URL は HTTPS を使用する必要があります
• イベントが間違っている - Webhook 設定の events フィルターを確認してください

​

署名検証が失敗する

最もよくある原因は、生のリクエストボディではなく、パース済みの JSON ボディを使用していることです。

// ❌ 誤り - 解析後のボディを使用している
const signature = crypto
  .createHmac('sha256', secret)
  .update(JSON.stringify(req.body))
  .digest('hex');

// ✅ 正解 - 生のボディを使用する
app.use('/webhook', express.raw({ type: 'application/json' }));
app.post('/webhook', (req, res) => {
  const signature = crypto
    .createHmac('sha256', secret)
    .update(req.body) // 生のバッファ
    .digest('hex');
});

​

その他の問題

• シークレットが誤っている - アカウント設定 から取得した正しいシークレットを使用していることを確認してください
• タイムアウトエラー - エンドポイントが 10 秒以内に応答するようにしてください