ウェブフック のセットアップ

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

概要

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

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

ダッシュボール 構成

ウェブフック エンドポイント を作成

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

1. ウェブフック 設定 に移動

   • Omise ダッシュボード にログイン
   • 設定 > ウェブフック に移動
   • ウェブフック を作成 ボタン をクリック

2. エンドポイント URL を構成

   • HTTPS エンドポイント URL を入力 (例: https://api.example.com/webhooks/omise)
   • エンドポイント がインターネット からアクセス可能であることを確認
   • エンドポイント は POST リクエスト を受け入れる必要があります

3. 購読する イベント を選択

   • すべてのイベント を選択してすべてのウェブフック 通知 を受け取る
   • または特定のイベント を選択 (charge.create、charge.complete、refund.create など)
   • イベント 購読 はいつでも変更できます

4. 保存 およびウェブフック キー を取得

   • 作成 をクリックしてウェブフック エンドポイント を生成
   • ウェブフック 署名キー をコピーして安全に保存
   • このキー はウェブフック シグネチャ を検証 するために使用されます (1回だけ表示されます)

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

ウェブフック 構成 ページ には以下が表示されます:

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

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

異なる目的で複数 のウェブフック エンドポイント を構成 できます:

本番環境 エンドポイント:
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

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

必須:

• 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;
    }
}

レスポンス 要件

エンドポイント はウェブフック 配信に正しく レスポンス する必要があります:

成功 レスポンス:

• 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 });

    // ウェブフック を非同期 で処理
    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})

        # ウェブフック を非同期 で処理
        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 はローカル 開発 サーバー へのセキュアなトンネル を作成し、本番環境 にデプロイ することなくウェブフック をテストできます。

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 をセットアップ

1. ngrok アカウント にサインアップ (無料ティア 利用可能)

   • ngrok.com を訪問
   • アカウント を作成して authtoken を取得

2. authtoken で ngrok を構成:

ngrok config add-authtoken YOUR_AUTHTOKEN

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

# 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

4. ngrok トンネル を作成:

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

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

5. 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

6. Omise ダッシュボール でウェブフック を構成:
   • HTTPS URL を使用: https://abc123.ngrok.io/webhooks/omise
   • テストする イベント を選択
   • 構成 を保存

ngrok Web インターフェース

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

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

テスト ウェブフック

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

Omise ダッシュボール はウェブフック 配信 をテストするツール を提供します:

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

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

テストモード でリアルイベント を作成してウェブフック をトリガー:

# テスト チャージ を作成 (charge.create ウェブフック をトリガー)
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 ウェブフック をトリガー)
# テストモード では、テストカード を使用すればチャージは自動完了

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

ベストプラクティス

セキュリティ

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

信頼性

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

パフォーマンス

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

// 例: ウェブフック 処理 用に Redis キュー を使用
const express = require('express');
const Queue = require('bull');
const app = express();

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

// ウェブフック エンドポイント
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 });
});

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

  // ウェブフック 処理 ロジック
  await processWebhook(event);
});

トラブルシューティング

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

問題: ウェブフック エンドポイント がイベント を受け取っていない

解決策:

• エンドポイント がインターネット からアクセス 可能な 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

問題: ウェブフック シグネチャ 検証 に失敗

解決策:

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

問題: ウェブフック タイムアウト

解決策:

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

FAQ

複数 のウェブフック エンドポイント を構成 できますか?

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

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

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

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

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

関連リソース

• イベント タイプ - すべてのウェブフック イベント タイプ の完全な参照
• セキュリティ - ウェブフック シグネチャ 検証 とベストプラクティス
• 再試行 ロジック - 再試行 動作 の理解 とべき等 の実装
• API 認証 - API キー と認証 方法
• テスト ガイド - Omise 統合 のテスト

次のステップ

ウェブフック エンドポイント をセットアップ した後:

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