Webhookのセットアップ

OmiseダッシュボードでWebhookエンドポイントを構成し、リアルタイム支払いイベント通知を受け取るようにサーバーをセットアップする方法を学習します。

概要

Webhookにより、Omiseはアカウント内のイベントが発生するときにリアルタイム通知をサーバーにプッシュできます。このガイドでは以下をカバーしています:

ダッシュボードでWebhookエンドポイントを作成および構成
セキュアなHTTPSエンドポイントをセットアップ
ngrokを使用したローカルテスト
複数エンドポイントを管理
Webhook構成を検証

ダッシュボード構成

Webhookエンドポイントを作成

OmiseダッシュボードでWebhookエンドポイントを作成するには、次の手順に従います:

Webhook設定に移動
- Omiseダッシュボードにログイン
- 設定 > Webhookに移動
- Webhookを作成ボタンをクリック
エンドポイントURLを構成
- HTTPSエンドポイントURLを入力 (例: https://api.example.com/webhooks/omise)
- エンドポイントがインターネットからアクセス可能であることを確認
- エンドポイントはPOSTリクエストを受け入れる必要があります
購読するイベントを選択
- すべてのイベントを選択してすべてのWebhook通知を受け取る
- または特定のイベントを選択 (charge.create、charge.complete、refund.create など)
- イベント購読はいつでも変更できます
保存およびWebhookキーを取得
- 作成をクリックしてWebhookエンドポイントを生成
- Webhook署名キーをコピーして安全に保存
- このキーはWebhookシグネチャを検証するために使用されます (1回だけ表示されます)

ダッシュボードインターフェース要素

Webhook構成ページには以下が表示されます:

エンドポイントURL: Webhookイベントの送信先
ステータス: アクティブ/非アクティブトグル
イベント: 購読済みイベントタイプのリスト
最近の配信: 最近のWebhook試行ログとレスポンスコード
署名キー: HMAC-SHA256シグネチャ検証に使用

複数エンドポイントを管理

異なる目的で複数のWebhookエンドポイントを構成できます:

本番環境エンドポイント:
URL: https://api.example.com/webhooks/omise
イベント: すべてのイベント
ステータス: アクティブ

バックアップエンドポイント:
URL: https://backup.example.com/webhooks/omise
イベント: 重要なイベントのみ (charge.complete、refund.create)
ステータス: アクティブ

分析エンドポイント:
URL: https://analytics.example.com/webhooks/omise
イベント: すべてのイベント
ステータス: アクティブ

複数エンドポイント用のベストプラクティス:

本番環境、ステージング、開発用に別々のエンドポイントを使用
異なるサービス (会計、分析、通知) 用に専用エンドポイントを作成
各エンドポイントの配信成功率を監視
未使用のエンドポイントを無効化してノイズを減らす

エンドポイント要件

HTTPSとSSL/TLS

すべてのWebhookエンドポイントはこれらのセキュリティ要件を満たす必要があります:

必須:

HTTPSプロトコル (HTTPはサポートされていません)
信頼されたCAからの有効なSSL/TLS証明書
TLS 1.2以上
強力な暗号スイート

推奨:

Let's Encrypt、DigiCertなどの信頼されたCAからの証明書
自動証明書更新
HSTS (HTTP Strict Transport Security)ヘッダー

# Nginx SSL構成例
server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    location /webhooks/omise {
        proxy_pass http://localhost:3000;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }
}

レスポンス要件

エンドポイントはWebhook配信に正しくレスポンスする必要があります:

成功レスポンス:

HTTPステータスコード: 200-299 (200 OKを推奨)
10秒以内にレスポンス
処理を待たずに迅速にレスポンス

失敗レスポンス:

HTTPステータスコード: 400-599は自動再試行をトリガー
200-299以外のステータスコードは失敗と見なされます

// Node.js/Express例
app.post('/webhooks/omise', async (req, res) => {
  try {
    // まずシグネチャを検証
    const isValid = verifySignature(req);
    if (!isValid) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    // 迅速にレスポンス (処理を待たない)
    res.status(200).json({ received: true });

    // Webhookを非同期で処理
    processWebhookAsync(req.body);
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

# Python/Flask例
@app.route('/webhooks/omise', methods=['POST'])
def handle_webhook():
    try:
        # まずシグネチャを検証
        if not verify_signature(request):
            return jsonify({'error': 'Invalid signature'}), 401

        # 迅速にレスポンス
        response = jsonify({'received': True})

        # Webhookを非同期で処理
        process_webhook_async(request.json)

        return response, 200
    except Exception as e:
        logging.error(f'Webhook error: {e}')
        return jsonify({'error': 'Internal server error'}), 500

ローカルテスト用ngrok

ngrokはローカル開発サーバーへのセキュアなトンネルを作成し、本番環境にデプロイすることなくWebhookをテストできます。

ngrokをインストール

macOS (Homebrew):

brew install ngrok/ngrok/ngrok

Linux:

curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | \
  sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && \
  echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | \
  sudo tee /etc/apt/sources.list.d/ngrok.list && \
  sudo apt update && sudo apt install ngrok

Windows:

choco install ngrok

ngrokをセットアップ

ngrokアカウントにサインアップ (無料ティア利用可能)
- ngrok.comを訪問
- アカウントを作成してauthtokenを取得
authtokenでngrokを構成:

ngrok config add-authtoken YOUR_AUTHTOKEN

ローカルサーバーを起動:

# Node.js
npm start
# または
node server.js

# Python
python app.py

# Ruby
ruby app.rb

# PHP
php -S localhost:3000

# Go
go run main.go

ngrokトンネルを作成:

# ローカルポート3000へのトンネルを作成
ngrok http 3000

# カスタムサブドメイン付き (有料プラン)
ngrok http 3000 --subdomain=myapp-webhooks

HTTPS転送URLをコピー:

ngrok by @inconshreveable

Session Status                online
Account                       your-account (Plan: Free)
Version                       3.0.0
Region                        United States (us)
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

Web Interface                 http://127.0.0.1:4040

OmiseダッシュボードでWebhookを構成:
- HTTPS URLを使用: https://abc123.ngrok.io/webhooks/omise
- テストするイベントを選択
- 構成を保存

ngrok Webインターフェース

http://127.0.0.1:4040でngrok Webインターフェースにアクセス:

すべてのHTTPリクエストとレスポンスを検査
デバッグ用にWebhookリクエストを再生
リクエストヘッダーとボディを表示
レスポンス時間とステータスコードをチェック

テストWebhook

ダッシュボードでのテスト

OmiseダッシュボードはWebhook配信をテストするツールを提供します:

Webhookセクションに移動
エンドポイントを選択
テストWebhookを送信をクリック
イベントタイプを選択 (charge.complete、refund.create など)
配信ステータスとレスポンスを確認

テストイベントをトリガー

テストモードでリアルイベントを作成してWebhookをトリガー:

# テスト課金を作成 (charge.create Webhookをトリガー)
curl https://api.omise.co/charges \
  -u skey_test_YOUR_SECRET_KEY: \
  -d "amount=100000" \
  -d "currency=THB" \
  -d "card=tokn_test_5xxxxxxxxxxxxx"

# 課金を完了 (charge.complete Webhookをトリガー)
# テストモードでは、テストカードを使用すれば課金は自動完了

# 払戻を作成 (refund.create Webhookをトリガー)
curl https://api.omise.co/charges/chrg_test_5xxxxxxxxxxxxx/refunds \
  -u skey_test_YOUR_SECRET_KEY: \
  -d "amount=50000"

ベストプラクティス

セキュリティ

Webhookシグネチャを常に検証してからイベントを処理
有効なSSL証明書を使用してすべてのエンドポイントにHTTPSを使用
Webhook署名キーをセキュアに保存 (環境変数、シークレットマネージャー)
レート制限を実装して不正使用を防止
すべてのWebhook配信をログして監査証跡を作成

信頼性

迅速にレスポンス (タイムアウトを回避するため10秒以内)
バックグラウンドジョブまたはキューを使用して非同期で処理
べき等を実装して重複配信を処理
Webhookの状態を監視してアラート付きで失敗を検出
開発およびステージング環境で定期的にテスト

パフォーマンス

メッセージキュー (Redis、RabbitMQ、AWS SQS)を処理に使用
高ボリューム用にロードバランサーでスケール
複数イベント処理時にデータベース操作をバッチ処理
頻繁にアクセスされるデータをキャッシュしてデータベース負荷を減らす
レスポンス時間用の監視およびメトリクスをセットアップ

// 例: Webhook処理用にRedisキューを使用
const express = require('express');
const Queue = require('bull');
const app = express();

// Webhook処理キューを作成
const webhookQueue = new Queue('webhooks', {
  redis: { host: 'localhost', port: 6379 }
});

// Webhookエンドポイント
app.post('/webhooks/omise', async (req, res) => {
  // シグネチャを検証
  if (!verifySignature(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // キューに追加して迅速にレスポンス
  await webhookQueue.add(req.body, {
    attempts: 3,
    backoff: { type: 'exponential', delay: 2000 }
  });

  res.status(200).json({ received: true });
});

// キューからWebhookを処理
webhookQueue.process(async (job) => {
  const event = job.data;
  console.log(`Processing webhook: ${event.key}`);

  // Webhook処理ロジック
  await processWebhook(event);
});

トラブルシューティング

一般的な問題とソリューション

問題: Webhookエンドポイントがイベントを受け取っていない

解決策:

エンドポイントがインターネットからアクセス可能なHTTPSであることを確認
ファイアウォールルールとセキュリティグループをチェック
Omiseダッシュボードでエンドポイントがアクティブであることを確認
サーバーログで受信リクエストをレビュー
curlまたはPostmanでエンドポイントをテスト

# エンドポイントアクセス可能性をテスト
curl -X POST https://your-domain.com/webhooks/omise \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

問題: SSL証明書エラー

解決策:

SSL証明書が有効で期限切れでないことを確認
証明書チェーンが完全であることを確認
証明書がドメイン名と一致することを確認
SSLテストツールを使用して問題を診断

# SSL証明書をチェック
openssl s_client -connect your-domain.com:443 -servername your-domain.com

# curlでSSLをテスト
curl -v https://your-domain.com/webhooks/omise

問題: Webhookシグネチャ検証に失敗

解決策:

正しいWebhook署名キーを使用していることを確認
生リクエストボディをシグネチャ検証に使用していることを確認
文字エンコーディングの問題をチェック
HMAC-SHA256アルゴリズムが正しく実装されていることを確認
セキュリティガイドで詳細な例を参照

問題: Webhookタイムアウト

解決策:

10秒以内にWebhookにレスポンス
バックグラウンドジョブ/キューに処理を移動
データベースクエリを最適化
タイムアウト監視とアラートを追加

FAQ

複数のWebhookエンドポイントを構成できますか?

はい、アカウントごとに複数のWebhookエンドポイントを構成できます。各エンドポイントは異なるイベントをサブスクライブでき、異なるサービスまたはEnvironmentにWebhookをルーティングできます。

ローカルテストにHTTPを使用できますか?

いいえ、すべてのWebhookエンドポイントは有効なSSL証明書を持つHTTPSを使用する必要があります。ローカルテストでは、ngrokまたは同様のトンネリングサービスを使用してHTTPSエンドポイントを作成してください。

エンドポイントがダウンした場合はどうなりますか?

Omiseは指数バックオフを使用して失敗したWebhook配信を自動的に再試行します。Webhookは7日間にわたって再試行されます。詳細は再試行ロジックガイドを参照してください。

次のステップ

Webhookエンドポイントをセットアップした後:

シグネチャ検証を実装 - セキュリティガイドで詳細な例を参照
イベントタイプをレビュー - 利用可能なイベントのためにイベントタイプ参照をチェック
再試行と失敗を処理 - 再試行ロジックの詳細とべき等を学習
統合をテスト - テスト課金と払戻を作成してWebhook配信を検証
Webhookの状態を監視 - 本番環境監視用にログとアラートをセットアップ

概要​

ダッシュボード構成​

Webhookエンドポイントを作成​

ダッシュボードインターフェース要素​

複数エンドポイントを管理​

エンドポイント要件​

HTTPSとSSL/TLS​

レスポンス要件​

ローカルテスト用ngrok​

ngrokをインストール​

ngrokをセットアップ​

ngrok Webインターフェース​

テストWebhook​

ダッシュボードでのテスト​

テストイベントをトリガー​

ベストプラクティス​

セキュリティ​

信頼性​

パフォーマンス​

トラブルシューティング​

一般的な問題とソリューション​

FAQ​

複数のWebhookエンドポイントを構成できますか?​

ローカルテストにHTTPを使用できますか?​

エンドポイントがダウンした場合はどうなりますか?​

関連リソース​

次のステップ​

概要

ダッシュボード構成

Webhookエンドポイントを作成

ダッシュボードインターフェース要素

複数エンドポイントを管理

エンドポイント要件

HTTPSとSSL/TLS

レスポンス要件

ローカルテスト用ngrok

ngrokをインストール

ngrokをセットアップ

ngrok Webインターフェース

テストWebhook

ダッシュボードでのテスト

テストイベントをトリガー

ベストプラクティス

セキュリティ

信頼性

パフォーマンス

トラブルシューティング

一般的な問題とソリューション

FAQ

複数のWebhookエンドポイントを構成できますか?

ローカルテストにHTTPを使用できますか?

エンドポイントがダウンした場合はどうなりますか?

関連リソース

次のステップ