웹훅 엔드포인트 추가

POST /v1/webhook-endpoints · 권한 webhook-endpoints:write · 모든 요금제

환경의 이벤트를 받는 엔드포인트를 추가합니다. 이벤트는 Standard Webhooks v1 방식으로 서명됩니다. 전달은 최소 한 번 이루어지므로 webhook-id 헤더로 중복을 제거하십시오.

서명 비밀 값. 응답에는 signing_secret(idp_whsec_…)이 한 번만 포함되며, 응답은 Cache-Control: no-store로 전달됩니다. 이 값은 다시 조회할 수 없으므로 즉시 저장하십시오. 같은 Idempotency-Key로 요청을 반복하면 비밀 값 없이 secret_redacted: true가 포함된 엔드포인트가 반환됩니다. 분실하였거나 유출된 경우 서명 비밀 값 교체를 사용하십시오.
URL. https만 허용되며, 포트는 없거나 443이어야 합니다. 사용자 정보나 fragment를 포함할 수 없고, IP 리터럴을 사용할 수 없으며, 최대 2,048자입니다. 리디렉션은 따라가지 않습니다.
이벤트. event_types에는 카탈로그의 이벤트 유형을 나열합니다. 목록이 비어 있으면 대량 발생 유형을 제외한 모든 유형이 대상이 됩니다.
한도. 환경당 활성화된 엔드포인트는 Free 3개, Startup 20개, Business 20개, Enterprise 50개까지 만들 수 있습니다.

요청

필드	유형	필수	설명
`url`	string	예	수신 URL(위 규칙 적용).
`key`	string	아니요	환경 내에서 고유한 고정 키: `[a-z0-9][a-z0-9_-]{0,63}`. 기본값은 `endpoint-<id의 마지막 8자>`.
`description`	string	아니요	최대 500자.
`event_types`	array	아니요	카탈로그 이벤트 유형, 최대 100개, 중복 불가. 비어 있거나 생략하면 대량 발생 유형을 제외한 모든 유형.
`event_schema_versions`	object	아니요	이벤트 유형 → 스키마 버전. 나열되지 않은 유형은 지원되는 가장 오래된 버전으로 전송됩니다.
`payload_mode`	string	아니요	`thin`(기본값: ID, 변경된 필드 이름과 상태 필드, 개인 데이터 없음) 또는 `full`(리소스의 관리 API 표현).
`rate_limit_per_second`	integer	아니요	이 엔드포인트로의 초당 전달 수 1–1,000; 기본값 50.
`status`	string	아니요	`enabled`(기본값) 또는 `disabled_by_user`.
`Idempotency-Key`	header	아니요	같은 키로 반복된 요청에 대해 응답(비밀 값 제외)을 재생합니다.

{
  "url": "https://hooks.example.com/keenauth",
  "key": "crm-sync",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"]
}

응답

201 Created와 함께 엔드포인트, 버전을 나타내는 ETag, 서명 비밀 값이 반환됩니다. 나머지 필드는 웹훅 엔드포인트 조회에 설명되어 있습니다.

{
  "id": "whe_01k8a3m5q7t9v1w3x5y7z9b2c4",
  "key": "crm-sync",
  "url": "https://hooks.example.com/keenauth",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"],
  "event_schema_versions": {},
  "payload_mode": "thin",
  "status": "enabled",
  "rate_limit_per_second": 50,
  "previous_secret_expires_at": null,
  "last_success_at": null,
  "failing_since": null,
  "version": 1,
  "created_at": "2026-10-26T09:00:00Z",
  "updated_at": "2026-10-26T09:00:00Z",
  "signing_secret": "idp_whsec_<secret>"
}

오류

HTTP	code	발생 조건
400	`unknown_field`	본문에 위에 나열되지 않은 필드가 있습니다.
403	`quota_exceeded`	환경이 이미 요금제에서 허용하는 활성 엔드포인트 수에 도달했거나, 요금제를 확인할 수 없습니다.
409	`conflict`	같은 환경의 다른 엔드포인트가 이 `key`를 사용하고 있습니다.
422	`validation_failed`	`/url required`, `/url invalid_webhook_url`, `/key invalid`, `/description too_long`, `/event_types unknown_event_type`, `/event_types duplicate`, `/event_types too_many`, `/event_schema_versions unsupported_schema_version`, `/payload_mode invalid`, `/rate_limit_per_second out_of_range`, `/status invalid`.
422	`idempotency_key_reuse`	다른 요청에 이미 사용된 `Idempotency-Key`를 사용했습니다.
401	`unauthenticated`	자격 증명이 없거나 잘못되었거나 취소되었습니다.
403	`insufficient_permissions`	자격 증명에 `webhook-endpoints:write` 권한이 없습니다.
429	`rate_limited`	요청 한도를 초과했습니다. `Retry-After` 기간 이후에 다시 시도하십시오.
503	`service_unavailable`	웹훅 관리 기능을 일시적으로 사용할 수 없습니다. `Retry-After` 기간 이후에 다시 시도하십시오.

예제

curl -X POST https://api.eu.keenauth.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f" \
  -d '{"url":"https://hooks.example.com/keenauth","key":"crm-sync","event_types":["user.created","user.updated"]}'

CLI: keenauth webhook-endpoints create --url https://hooks.example.com/keenauth --key crm-sync --event-types user.created,user.updated