MENU
  1. ホーム
  2. Column
  3. Webhookの「ペイロード」って何？JSONデータの中身を3分で理解

Webhookの「ペイロード」って何？JSONデータの中身を3分で理解

Column

Webhook実装を始めたばかりで、「ペイロードって何？」「JSONデータの中身がよく分からない」と困っていませんか？GitHubやStripe、Slackなどのサービス連携で必ず出てくる「ペイロード」という言葉。実は、これはWebhookで送られてくるデータの中身そのものを指しています。

この記事では、Webhookペイロードの基本概念から実際の使い方まで、初心者エンジニアでも3分で理解できるように解説します。GitHub、Stripe、Slackの実例を使って、ペイロードの構造と活用方法を具体的に見ていきましょう。

目次

Webhookペイロードとは？「荷物の中身」に例えると分かりやすい

Webhookペイロードを理解するには、宅配便に例えるのが一番分かりやすいです。Webhookは「荷物が届いたよ」という通知、そしてペイロードは「その荷物の中身」に相当します。

ペイロードの基本概念

ペイロード（payload）とは、Webhookで送信される実際のデータ本体のことです。Webhookは、あるイベントが発生したときに自動的にHTTP POSTリクエストを送信する仕組みですが、このリクエストのボディ部分に含まれるJSON形式のデータがペイロードです。

具体的には以下のような情報が含まれます：

  • イベントの種類（プッシュ、決済完了、メッセージ送信など）
  • イベントが発生した日時
  • イベントに関連するデータ（ユーザー情報、金額、コミット内容など）
  • イベントのステータスや追加のメタデータ

なぜ「ペイロード」と呼ぶのか

「payload」という言葉は、もともと航空業界や物流業界で使われていた用語で、「輸送機が運ぶ有料の荷物」という意味です。ロケットや飛行機が運ぶ「本当に必要なもの」を指す言葉として使われてきました。

IT業界では、この概念が転用され、通信パケットやHTTPリクエストの中で「本当に必要なデータ部分」をペイロードと呼ぶようになりました。HTTPヘッダーやメタデータを除いた、純粋なデータ本体がペイロードです。

Webhookの仕組みとペイロードの関係

Webhookは「イベント駆動型」の通信方式です。従来のAPI（ポーリング方式）では、クライアント側が定期的にサーバーに「何か変更ありましたか？」と問い合わせる必要がありましたが、Webhookではイベントが発生したときにサーバー側から自動的に通知してくれます。

この通知の際に送られてくるのがペイロードです。つまり、Webhookという「配達システム」を使って、ペイロードという「荷物」が届けられるイメージです。

実際のペイロードを見てみよう（GitHub・Stripe・Slackの実例）

実際のペイロードがどのような構造になっているのか、主要なサービスの実例を見ていきましょう。

GitHub Webhook：プッシュイベントのペイロード

GitHubにコードをプッシュしたときに送られてくるペイロードの例です：

{
  "ref": "refs/heads/main",
  "before": "abc123...",
  "after": "def456...",
  "repository": {
    "id": 123456789,
    "name": "my-project",
    "full_name": "username/my-project",
    "owner": {
      "name": "username",
      "email": "user@example.com"
    }
  },
  "pusher": {
    "name": "username",
    "email": "user@example.com"
  },
  "commits": [
    {
      "id": "def456...",
      "message": "Fix bug in payment module",
      "timestamp": "2024-12-06T10:30:00Z",
      "author": {
        "name": "username",
        "email": "user@example.com"
      },
      "added": ["src/payment.js"],
      "modified": ["README.md"],
      "removed": []
    }
  ]
}

このペイロードから、誰が、いつ、どのブランチに、どんな変更をプッシュしたかという情報をすべて取得できます。

Stripe Webhook：決済完了のペイロード

Stripeで決済が完了したときに送られてくるペイロードの例です：

{
  "id": "evt_1234567890",
  "object": "event",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_1234567890",
      "amount": 5000,
      "currency": "jpy",
      "status": "succeeded",
      "customer": "cus_1234567890",
      "payment_method": "pm_1234567890",
      "created": 1701849600
    }
  },
  "created": 1701849600
}

このペイロードから、決済金額、通貨、顧客ID、決済ステータスなどの重要な情報を取得できます。この情報を使って、自動的に領収書を送信したり、会員ステータスを更新したりできます。

Slack Webhook：メッセージ送信のペイロード

Slackへメッセージを送信する際のペイロード例です（Incoming Webhook）：

{
  "text": "デプロイが完了しました",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*デプロイ完了通知*\n本番環境へのデプロイが正常に完了しました。"
      }
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*環境:*\n本番環境"
        },
        {
          "type": "mrkdwn",
          "text": "*ブランチ:*\nmain"
        }
      ]
    }
  ]
}

このペイロードでは、メッセージ本文、フォーマット、追加フィールドなどを指定して、リッチなメッセージをSlackに送信できます。

ペイロードの共通構造

多くのWebhookペイロードには共通する構造があります：

  • イベント識別子: idやevent_idなどのユニークなID
  • イベントタイプ: typeやeventフィールドで何が起きたかを示す
  • タイムスタンプ: createdやtimestampでイベント発生時刻を記録
  • データ本体: dataやobjectフィールドに実際の情報が格納
  • メタデータ: APIバージョン、リクエストIDなどの追加情報

ペイロードを受け取る3ステップ実装（Node.js/Python）

実際にペイロードを受け取って処理する実装を見ていきましょう。

Step1: Webhook受信エンドポイントの作成

まず、Webhookを受け取るためのHTTPエンドポイントを作成します。

Node.js（Express）での実装例：

const express = require('express');
const app = express();

// JSONペイロードをパースするミドルウェア
app.use(express.json());

// Webhook受信エンドポイント
app.post('/webhook', (req, res) => {
  console.log('Webhookを受信しました');
  
  // ペイロード全体を確認
  console.log('ペイロード:', JSON.stringify(req.body, null, 2));
  
  // 200 OKを返す（重要！）
  res.status(200).send('Webhook received');
});

app.listen(3000, () => {
  console.log('Webhookサーバーがポート3000で起動しました');
});

Python（Flask）での実装例：

from flask import Flask, request, jsonify
import json

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    print('Webhookを受信しました')
    
    # ペイロードを取得
    payload = request.json
    print('ペイロード:', json.dumps(payload, indent=2))
    
    # 200 OKを返す（重要！）
    return jsonify({'status': 'success'}), 200

if __name__ == '__main__':
    app.run(port=3000, debug=True)

重要なポイントは、必ず200番台のHTTPステータスコードを返すことです。200を返さないと、Webhookサービス側が「失敗した」と判断して、何度もリトライを繰り返すことがあります。

Step2: ペイロードのパース（JSON解析）

受け取ったペイロードから必要なデータを取り出します。

Node.jsでのパース例：

app.post('/webhook/github', (req, res) => {
  const payload = req.body;
  
  // イベントタイプを確認
  const eventType = req.headers['x-github-event'];
  
  if (eventType === 'push') {
    // プッシュイベントの処理
    const branch = payload.ref.replace('refs/heads/', '');
    const commits = payload.commits;
    const pusher = payload.pusher.name;
    
    console.log(`${pusher}さんが${branch}ブランチに${commits.length}件のコミットをプッシュしました`);
    
    // 各コミットの詳細を処理
    commits.forEach(commit => {
      console.log(`- ${commit.message}`);
    });
  }
  
  res.status(200).send('OK');
});

Pythonでのパース例：

@app.route('/webhook/github', methods=['POST'])
def github_webhook():
    payload = request.json
    
    # イベントタイプを確認
    event_type = request.headers.get('X-GitHub-Event')
    
    if event_type == 'push':
        # プッシュイベントの処理
        branch = payload['ref'].replace('refs/heads/', '')
        commits = payload['commits']
        pusher = payload['pusher']['name']
        
        print(f"{pusher}さんが{branch}ブランチに{len(commits)}件のコミットをプッシュしました")
        
        # 各コミットの詳細を処理
        for commit in commits:
            print(f"- {commit['message']}")
    
    return jsonify({'status': 'success'}), 200

Step3: 必要なデータの取り出しと活用

パースしたデータを使って、実際の処理を行います。例えば、データベースへの保存、外部APIへの送信、通知の送信などです。

app.post('/webhook/stripe', async (req, res) => {
  const payload = req.body;
  
  // Stripeの決済完了イベント
  if (payload.type === 'payment_intent.succeeded') {
    const paymentIntent = payload.data.object;
    
    // 必要なデータを取り出す
    const amount = paymentIntent.amount;
    const currency = paymentIntent.currency;
    const customerId = paymentIntent.customer;
    
    try {
      // データベースに保存
      await db.payments.create({
        stripePaymentId: paymentIntent.id,
        customerId: customerId,
        amount: amount,
        currency: currency,
        status: 'completed',
        createdAt: new Date(paymentIntent.created * 1000)
      });
      
      // 顧客に領収書メールを送信
      await sendReceiptEmail(customerId, amount, currency);
      
      console.log(`決済完了: ${amount}${currency}`);
      
    } catch (error) {
      console.error('処理エラー:', error);
      // エラーでも200を返す（リトライを防ぐため）
      return res.status(200).send('Error logged');
    }
  }
  
  res.status(200).send('OK');
});

ペイロードの実用例：Slackに通知を自動送信

実際のユースケースとして、GitHubのプッシュイベントをSlackに自動通知する実装を見てみましょう。

GitHub→Slackの連携実装

GitHubからのWebhookペイロードを受け取り、Slackに整形した通知を送信します。

const express = require('express');
const axios = require('axios');
const app = express();

app.use(express.json());

// Slack Incoming Webhook URL（環境変数から取得）
const SLACK_WEBHOOK_URL = process.env.SLACK_WEBHOOK_URL;

app.post('/webhook/github', async (req, res) => {
  const payload = req.body;
  const eventType = req.headers['x-github-event'];
  
  if (eventType === 'push') {
    // ペイロードから必要データを抽出
    const branch = payload.ref.replace('refs/heads/', '');
    const pusher = payload.pusher.name;
    const commits = payload.commits;
    const repoName = payload.repository.full_name;
    
    // Slackメッセージを構築
    const slackMessage = {
      text: `新しいコミットがプッシュされました`,
      blocks: [
        {
          type: "header",
          text: {
            type: "plain_text",
            text: "🚀 新しいコミットがプッシュされました"
          }
        },
        {
          type: "section",
          fields: [
            {
              type: "mrkdwn",
              text: `*リポジトリ:*\n${repoName}`
            },
            {
              type: "mrkdwn",
              text: `*ブランチ:*\n${branch}`
            },
            {
              type: "mrkdwn",
              text: `*プッシュ者:*\n${pusher}`
            },
            {
              type: "mrkdwn",
              text: `*コミット数:*\n${commits.length}件`
            }
          ]
        },
        {
          type: "divider"
        },
        {
          type: "section",
          text: {
            type: "mrkdwn",
            text: "*コミット一覧:*"
          }
        }
      ]
    };
    
    // 各コミットを追加
    commits.forEach(commit => {
      slackMessage.blocks.push({
        type: "section",
        text: {
          type: "mrkdwn",
          text: `• \`${commit.id.substring(0, 7)}\` ${commit.message}\n   _by ${commit.author.name}_`
        }
      });
    });
    
    // Slackに送信
    try {
      await axios.post(SLACK_WEBHOOK_URL, slackMessage);
      console.log('Slack通知を送信しました');
    } catch (error) {
      console.error('Slack送信エラー:', error.message);
    }
  }
  
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('GitHub→Slack連携サーバーが起動しました');
});

ペイロードから必要データを抽出

この実装のポイントは、GitHubのペイロードから以下のデータを抽出している点です：

  • payload.ref: ブランチ名（refs/heads/を削除）
  • payload.pusher.name: プッシュしたユーザー名
  • payload.commits: コミットの配列
  • payload.repository.full_name: リポジトリ名
  • commit.id: コミットハッシュ（最初の7文字を使用）
  • commit.message: コミットメッセージ

実装コード例（コピペOK）

環境変数の設定も含めた完全な実装例です。

.envファイル：

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
PORT=3000

package.json：

{
  "name": "github-slack-webhook",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.2",
    "axios": "^1.6.0",
    "dotenv": "^16.3.1"
  }
}

この実装をコピペして、環境変数を設定すれば、すぐにGitHub→Slack連携が動作します。

よくあるトラブルと解決法

Webhook実装でよく遭遇するトラブルと、その解決方法を紹介します。

ペイロードが受け取れない（エンドポイント設定ミス）

症状：Webhookを設定したのに、サーバーにリクエストが届かない。

原因と解決法：

  • ファイアウォールでブロックされている: サーバーのファイアウォール設定を確認し、HTTPSポート（443）を開放する
  • URLが間違っている: Webhook URLが正確か再確認（https://のスキーマ、ドメイン名、パス）
  • ローカル環境で開発している: ngrokやCloudflare Tunnelを使って、ローカル環境を外部公開する
  • HTTPSが必須なのにHTTPを使っている: 多くのサービスはHTTPSのエンドポイントのみ対応

デバッグ方法：

# ngrokでローカル環境を公開（開発時）
ngrok http 3000

# サーバーログを確認
tail -f /var/log/webhook-server.log

# Webhook配信履歴を確認（GitHubの場合）
# Settings > Webhooks > 対象Webhook > Recent Deliveries

JSONのパースエラー（文字エンコーディング問題）

症状：SyntaxError: Unexpected token in JSONなどのエラーが発生する。

原因と解決法：

  • Content-Typeが正しく設定されていない: ミドルウェアでexpress.json()を使用しているか確認
  • ペイロードが空: サービス側の設定で、空のペイロードを送信していないか確認
  • 文字エンコーディングの問題: UTF-8以外のエンコーディングが使われている場合、明示的に変換が必要

対処コード例：

app.post('/webhook', (req, res) => {
  try {
    // ペイロードが存在するか確認
    if (!req.body || Object.keys(req.body).length === 0) {
      console.warn('空のペイロードを受信しました');
      return res.status(400).send('Empty payload');
    }
    
    // ペイロードを処理
    const payload = req.body;
    console.log('ペイロード受信:', JSON.stringify(payload, null, 2));
    
    res.status(200).send('OK');
    
  } catch (error) {
    console.error('パースエラー:', error.message);
    // エラーでも200を返して、リトライを防ぐ
    res.status(200).send('Parse error logged');
  }
});

データが空・nullの場合の対処法

症状：期待するフィールドがundefinedやnullになっている。

原因と解決法：

  • イベントタイプによってペイロード構造が異なる: イベントタイプごとに条件分岐が必要
  • オプショナルなフィールドを参照している: 必須フィールドかどうかAPIドキュメントで確認
  • ネストされたオブジェクトのnullチェック不足: オプショナルチェイニング（?.）を使用

安全なデータアクセス例：

app.post('/webhook', (req, res) => {
  const payload = req.body;
  
  // オプショナルチェイニングで安全にアクセス
  const userName = payload.user?.name || '不明なユーザー';
  const email = payload.user?.email || 'メールアドレスなし';
  const commits = payload.commits || [];
  
  // 配列の長さをチェック
  if (commits.length === 0) {
    console.log('コミットが含まれていません');
    return res.status(200).send('No commits');
  }
  
  // デフォルト値を設定
  const branch = payload.ref?.replace('refs/heads/', '') || 'main';
  
  console.log(`${userName}さんが${branch}ブランチに${commits.length}件のコミットをプッシュ`);
  
  res.status(200).send('OK');
});

Pythonの場合：

@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.json or {}
    
    # getメソッドでデフォルト値を設定
    user_name = payload.get('user', {}).get('name', '不明なユーザー')
    email = payload.get('user', {}).get('email', 'メールアドレスなし')
    commits = payload.get('commits', [])
    
    # 配列の長さをチェック
    if not commits:
        print('コミットが含まれていません')
        return jsonify({'status': 'no commits'}), 200
    
    # デフォルト値を設定
    ref = payload.get('ref', 'refs/heads/main')
    branch = ref.replace('refs/heads/', '')
    
    print(f"{user_name}さんが{branch}ブランチに{len(commits)}件のコミットをプッシュ")
    
    return jsonify({'status': 'success'}), 200

まとめ：ペイロードを理解すればWebhook連携がスムーズに

Webhookペイロードは、イベント駆動型のサービス連携において最も重要なデータ本体です。この記事で解説したポイントをまとめます：

  • ペイロードとは: Webhookで送られてくるJSON形式のデータ本体
  • 実際の構造: GitHub、Stripe、Slackなど、サービスごとに構造は異なるが、共通パターンが存在
  • 実装の基本: エンドポイント作成→JSON解析→データ取り出し→処理の3ステップ
  • 実用例: GitHub→Slackの自動通知など、実際のユースケースで応用可能
  • トラブル対処: エンドポイント設定、パースエラー、null対応など、よくある問題の解決法を把握

ペイロードの基本を理解すれば、さまざまなサービス間の連携がスムーズに実装できるようになります。まずは小規模なWebhook連携から始めて、徐々に複雑な処理へとステップアップしていきましょう。

Webhookをさらに活用する関連記事

Webhookペイロードを理解したら、API連携やデータベース操作などの関連技術も習得して、より高度な自動化システムを構築しましょう：

データベース・データ管理

AI・自動化ツール

Column
API連携 GitHub JSON Node.js Python Slack Stripe Webhook ペイロード 開発者ツール
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！

関連記事

目次