このページでは、開発中の webhook 連携のテストや、本番環境での問題のデバッグに役立つツールと手法を解説します。

​
ローカル開発

​
ローカルサーバーの公開

Webhook はインターネット経由であなたのサーバーに到達する必要があるため、ローカルの開発サーバーを公開する必要があります。

​
Cloudflare Tunnels の利用

Cloudflare Tunnels は、アカウント登録やファイアウォールのポート開放なしで、ローカル開発サーバーを安全にインターネットへ公開できる無料の方法です。 
# GitHubのリリースからcloudflaredをダウンロードするか、パッケージマネージャーを利用します

# ローカルサーバーを公開する
cloudflared tunnel --url localhost:3000

# 出力例:
# クイックトンネルが作成されました！次のURLにアクセスしてください（到達可能になるまで時間がかかる場合があります）:
# https://abc123.trycloudflare.com
Webhook の設定で、提供された URL を使用してください： 
{
  "url": "https://abc123.trycloudflare.com/webhook"
}

​
よくある問題のデバッグ

​
Webhook が届かない

  1. URL の到達性を確認 – エンドポイントが外部からアクセス可能であることを確認する
  2. HTTPS を確認 – Webhook の URL は必ず HTTPS を使用する
  3. ファイアウォール設定を確認 – Webhook 用ポートへの受信接続を許可する
  4. イベントフィルターを確認 – 対象のイベントタイプを購読していることを確認する

​
署名検証が失敗する

  1. シークレットキーを確認 – 正しいシークレットを使用していることを確認してください
  2. 生のボディを使用しているか確認 – 生のリクエストボディを使用していることを確認してください： 
// ❌ 誤り - 解析後のボディを使用している
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');
});