メインコンテンツへスキップ
バージョン: 最新版

Webhook シークレット API

Interactive Webhook Tester​

Explore webhook events, view example payloads, and test your endpoint:

インタラクティブWebhookテスター

Webhookイベントを探索し、エンドポイントをテスト

Triggered when a charge is completed successfully

POSTcharge.complete
{
  "object": "event",
  "id": "evnt_test_5h2m123lxlx4z7yh9a2",
  "livemode": false,
  "location": "/events/evnt_test_5h2m123lxlx4z7yh9a2",
  "webhook_deliveries": [],
  "data": {
    "object": "charge",
    "id": "chrg_test_5h2m123abc456def",
    "amount": 100000,
    "currency": "thb",
    "description": "Test charge",
    "status": "successful",
    "authorized": true,
    "paid": true,
    "captured": true,
    "capture": true,
    "refunded": 0,
    "reversed": false,
    "voided": false,
    "expired": false,
    "disputable": true,
    "capturable": false,
    "reversible": false,
    "transaction": "trxn_test_5h2m123abc456def",
    "source_of_fund": "card",
    "failure_code": null,
    "failure_message": null,
    "card": {
      "object": "card",
      "id": "card_test_5h2m123abc456def",
      "livemode": false,
      "brand": "Visa",
      "last_digits": "4242",
      "name": "Test User",
      "expiration_month": 12,
      "expiration_year": 2025,
      "fingerprint": "FpEYKqwFa3znwjpHlEHjHg==",
      "security_code_check": true
    },
    "created_at": "2026-03-09T09:55:36.832Z"
  },
  "key": "charge.complete",
  "created_at": "2026-03-09T09:55:36.833Z"
}

Webhook シークレット APIを使用すると、Webhookの真正性を検証するために使用される署名シークレットを管理できます。Omiseから送信される各Webhookイベントには、署名シークレットを使用して検証できる署名が含まれており、イベントがOmiseから本物であることを確認できます。

概要​

Webhookシークレットは以下を提供します：

  • イベントの真正性 - Webhookが攻撃者ではなくOmiseからのものであることを検証
  • 改ざん検出 - Webhookペイロードが変更されたかどうかを検出
  • 複数のシークレット - ダウンタイムなしでキーローテーションをサポート
  • 安全なキー管理 - プログラムでシークレットを作成、一覧表示、削除

Webhook署名の仕組み​

  1. シークレットの作成 - API経由で署名シークレットを作成
  2. 署名の生成 - Omiseがシークレットを使用して各Webhookに署名
  3. 署名の検証 - サーバーが処理前に署名を検証
  4. シークレットのローテーション - セキュリティ強化のために定期的にシークレットをローテーション

Webhook署名の構造​

各Webhookリクエストには署名ヘッダーが含まれます：

  • Omise-Signature - 16進数エンコードされたHMAC-SHA256署名（シークレットローテーション中は2つのカンマ区切りの署名が含まれる場合があります）
  • Omise-Signature-Timestamp - 署名が生成されたUnixタイムスタンプ

Webhook署名の検証​

Webhook署名を検証するには：

  1. ヘッダーからタイムスタンプと署名を抽出
  2. タイムスタンプと生のリクエストボディを連結
  3. 署名シークレットを使用してHMAC-SHA256を計算
  4. 計算された署名と受信した署名を比較
  5. リプレイ攻撃を防ぐためにタイムスタンプが最近（5分以内）であることを検証
import hmac
import hashlib
import time

def verify_webhook(payload, signature, timestamp, secret):
    # タイムスタンプが5分以内かチェック
    current_time = int(time.time())
    if abs(current_time - int(timestamp)) > 300:
        return False

    # 期待される署名を計算
    message = f"{timestamp}.{payload}"
    expected_sig = hmac.new(
        secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    # 署名を安全に比較
    return hmac.compare_digest(expected_sig, signature)

シークレットオブジェクトの構造​

各Webhookシークレットには以下が含まれます：

  • Secret ID - 一意の識別子（whsec_*）
  • Secret Value - 署名キー（作成時のみ表示）
  • Created At - シークレットが作成された日時
  • Livemode - ライブモードまたはテストモードのシークレットかどうか

主なユースケース​

Webhook検証​

処理前に、受信したWebhookがOmiseから本物であることを検証します。

キーローテーション​

新しいシークレットを作成し、両方を受け入れるように検証コードを更新してから、古いシークレットを削除します。

セキュリティコンプライアンス​

コンプライアンス要件のためにシークレットの作成と削除の監査証跡を維持します。

マルチ環境セットアップ​

開発、ステージング、本番環境で別々のシークレットを使用します。

利用可能なエンドポイント​

ベストプラクティス​

推奨事項​

  • Webhookを処理する前に常に署名を検証する
  • リプレイ攻撃を防ぐためにタイムスタンプを確認する
  • 定期的にシークレットをローテーションする（90日ごとを推奨）
  • ローテーション期間中は複数のシークレットをサポートする
  • 環境変数またはシークレットマネージャーにシークレットを安全に保存する
  • タイミング攻撃を防ぐために定数時間比較を使用する

避けるべきこと​

  • アプリケーションログにシークレットを記録しない
  • ソースコードにシークレットをハードコーディングしない
  • 開発環境でも検証をスキップしない
  • リプレイ攻撃を防ぐためタイムスタンプチェックを無視しない
  • 環境間でシークレットを共有しない

セキュリティに関する考慮事項​

シークレットの保存​

  • 安全なシークレット管理システム（AWS Secrets Manager、HashiCorp Vaultなど）にシークレットを保存
  • バージョン管理にシークレットをコミットしない
  • デプロイメントには環境変数を使用

キーローテーション​

  • 古いシークレットを削除する前に新しいシークレットを作成
  • 移行中は両方のシークレットをチェックするように検証コードを更新
  • 新しいシークレットが正しく動作することを確認してから古いシークレットを削除
  • 24〜48時間以内にローテーションを完了することを目指す

リプレイ攻撃の防止​

  • 常にタイムスタンプヘッダーを検証
  • 5分より古いタイムスタンプのWebhookを拒否
  • イベントIDに基づく冪等性の実装を検討

関連リソース​

お困りですか？ Webhookガイドを確認するか、support@omise.coにお問い合わせください