keenauth_webhook_endpoint

keenauth_webhook_endpoint リソースは、ウェブフックエンドポイントを管理します。ウェブフックエンドポイントは、環境のイベントを受信する HTTPS アドレスで、Standard Webhooks で署名されます。プロバイダは署名シークレットを、指定された RSA 公開鍵で暗号化した状態でのみ state に保存します。

resource "keenauth_webhook_endpoint" "orders" {
  key         = "orders"
  url         = "https://hooks.example.com/keenauth"
  description = "Order service"
  event_types = ["user.created", "user.updated", "organization.created"]
  event_schema_versions = {
    "user.created" = 1
  }
  public_key = file("${path.module}/webhook-secret-key.pub.pem")

  rotation_trigger          = time_rotating.webhook_secret.id
  previous_secret_ttl_hours = 48
}

resource "time_rotating" "webhook_secret" {
  rotation_days = 90
}

output "orders_webhook_secret_encrypted" {
  value = keenauth_webhook_endpoint.orders.encrypted_signing_secret
}

引数

• url は必須です。https のみ使用でき、ポートを指定しない場合またはポート 443 のみ、ユーザー情報とフラグメントは使用できず、IP アドレスではなくホスト名を指定する必要があります（最大 2048 文字）。
• key は環境内で一意です（^[a-z0-9][a-z0-9_-]{0,63}$）。省略すると、API が endpoint-<ID の末尾 8 文字> を自動的に生成します。
• event_types はカタログのイベントタイプを一覧にします（最大 100 件）。空のセットはデフォルトで、高頻度の authentication.* タイプを除くすべてのタイプを意味します。これらは明示的に指定する必要があります。
• event_schema_versions は、イベントタイプをペイロードのスキーマバージョンに対応付けます。各タイプは、そのエンドポイントが受信するタイプである必要があります。
• payload_mode は thin（デフォルト。ID、変更されたフィールド名、ステータスフィールドのみを含み、個人データは含みません）または full です。
• rate_limit_per_second は 1 から 1000 までで、デフォルトは 50 です。
• status は enabled（デフォルト）または disabled_by_user です。

すべての引数はその場で変更されます。更新時には、変更されたフィールドのみを JSON Merge Patch として送信し、最後に読み取った ETag を If-Match として付与します。最後の読み取り後にエンドポイントが別の場所で変更されていた場合、適用は 412 で失敗し、何も変更されません。その場合は plan を再度実行して、ドリフトを確認してください。

署名シークレットは平文で保存されません

API が署名シークレット（idp_whsec_…）を返すのは、エンドポイントの作成時とシークレットのローテーション時のみです。public_key を指定すると、プロバイダはシークレットを RSA-OAEP（SHA-256、MGF1 SHA-256、空のラベル）で暗号化し、base64 の暗号文のみを encrypted_signing_secret に書き込みます。public_key を指定しない場合、シークレットは破棄されます。後から keenauth webhook-endpoints rotate-secret でローテーションするか、public_key を設定してください。平文のシークレットが state、plan ファイル、出力、ログに残ることはありません。

鍵ペアは OpenTofu の外で一度だけ作成し、秘密鍵は構成に含めないようにしてください。

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out webhook-secret-key.pem
openssl pkey -in webhook-secret-key.pem -pubout -out webhook-secret-key.pub.pem

tofu apply の後、シークレットを復号して受信側に渡します。

tofu output -raw orders_webhook_secret_encrypted | base64 -d | \
  openssl pkeyutl -decrypt -inkey webhook-secret-key.pem \
    -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256

public_key は、PEM 形式の RSA 公開鍵（PUBLIC KEY または RSA PUBLIC KEY）で、2048 ビット以上である必要があります。秘密鍵や、それより小さい鍵は plan 時に拒否されます。

ローテーション

シークレットは、public_key を設定または変更したとき、および rotation_trigger が新しい値に変わったとき（例：time_rotating リソースの ID）にローテーションされます。ローテーション後も、古いシークレットは新しいシークレットと並行して previous_secret_ttl_hours（0 から 168。API のデフォルトは 24。0 を指定するとすぐに破棄されます）の間、署名に使用され続けます。これにより、受信側はイベントを取りこぼさずに切り替えられます。previous_secret_expires_at には、古いシークレットが無効になる時刻が表示されます。public_key を削除しても encrypted_signing_secret が削除されるだけで、シークレットはローテーションされません。

上限とステータス

有効なエンドポイントは、環境ごとのプランの上限に含まれます。上限は Free 3、Startup 20、Business 20、Enterprise 50 です。上限を超えて作成または有効化しようとすると 403 quota_exceeded で失敗します。別のエンドポイントを無効化または削除するか、プランをアップグレードしてください。

KeenAuth は、失敗が続くエンドポイント（disabled_by_failure）や、受信側が 410 Gone を返すエンドポイント（disabled_by_receiver）を無効化します。次の plan では、構成された status への変更が表示され、適用するとエンドポイントが再び有効になります。

インポート

エンドポイントの ID またはキーを指定してインポートします。

tofu import keenauth_webhook_endpoint.orders orders

署名シークレットは読み戻せないため、インポート後は encrypted_signing_secret が空になります。構成で public_key を設定している場合、次の apply でシークレットがローテーションされ、新しいシークレットが暗号化された状態で配信されます。

テスト送信、リプレイ、配信の再試行は一回限りの操作であり、構成には含めません。これらには keenauth webhook-endpoints test、replay、deliveries を使用してください。