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입니다.

모든 인수는 제자리에서(in place) 변경됩니다. 업데이트 시에는 변경된 필드만 JSON Merge Patch로 전송되며, 마지막으로 읽은 ETag를 If-Match로 함께 보냅니다. 마지막 읽기 이후 엔드포인트가 다른 곳에서 변경되었다면 적용이 412 오류로 실패하고 아무것도 변경되지 않습니다. 이 경우 plan을 다시 실행하여 드리프트를 검토하십시오.

서명 시크릿은 평문으로 저장되지 않습니다

API는 엔드포인트를 생성할 때와 시크릿을 교체할 때에만 서명 시크릿(idp_whsec_…)을 반환합니다. public_key를 지정하면 프로바이더는 RSA-OAEP(SHA-256, MGF1 SHA-256, 빈 label)로 시크릿을 암호화하고, 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 단계에서 거부됩니다.

교체(Rotation)

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로 되돌리는 변경이 표시되며, 이를 적용하면 엔드포인트가 다시 활성화됩니다.

가져오기(Import)

엔드포인트 ID 또는 key로 가져올 수 있습니다.

tofu import keenauth_webhook_endpoint.orders orders

서명 시크릿은 다시 읽을 수 없으므로, 가져오기 후 encrypted_signing_secret은 비어 있습니다. 구성에 public_key가 설정되어 있다면 다음 apply에서 시크릿이 교체되고, 새 시크릿이 암호화된 상태로 전달됩니다.

테스트 전송, 재전송, 전달 재시도는 일회성 작업이며 구성에 포함되지 않습니다. 이러한 작업에는 keenauth webhook-endpoints test, replay, deliveries 명령을 사용하십시오.