Webhook 설정 조회 | ToAPIs Documentation

GET

/api/v1/webhook

중국 본토 사용자 안내: 중국 본토 사용자는 https://api.toapis.cn 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 https://api.toapis.com 을 https://api.toapis.cn 로 바꿔 주세요.

동작

지정 키의 Webhook 설정을 읽어 콜백 URL, 활성 상태, 최근 전송 상태를 확인합니다. Webhook 설정은 모델 키당 하나이며 소프트 삭제된 키도 읽을 수 있습니다. 비밀 키 설정 여부는 secret_configured만 반환하고 비밀 키 원문은 반환하지 않습니다.

미설정 URL과 시각은 null이며 관리 API의 시각은 RFC 3339입니다. 상태 조회 실패 시 health.state=unknown이 되지만 설정 기록 실패를 의미하지는 않습니다.

인증

Authorizationstring헤더필수

시스템 액세스 토큰 Bearer YOUR_SYSTEM_ACCESS_TOKEN 을 사용하며 본인 계정만 접근할 수 있습니다. 모델 Key 는 허용하지 않습니다. X-User-Id 는 필요 없으며 관리자나 팀 권한으로 범위를 우회할 수 없습니다.

요청 매개변수

api_key_idinteger쿼리필수

본인 일반 모델 Key 의 양의 정수 ID 이며 sk- 비밀 키나 액세스 토큰이 아닙니다. 쿼리 매개변수는 양의 정수여야 하며 생략이나 null 은 거부합니다.

api_key_id가 없거나 양의 정수가 아니면 400, 대상 키가 없거나 타인 소유이면 404, 레이트 리밋 시 429입니다. mode=off는 쓰기만 제한하고 이 조회에는 영향이 없습니다.

요청 예제

요청 예시

curl --request GET \
  --url 'https://api.toapis.com/api/v1/webhook?api_key_id=123' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

응답 예제

응답 예시

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "enabled": false,
    "url": null,
    "secret_configured": false,
    "previous_secret_expires_at": null,
    "updated_at": null,
    "mode": "enforce",
    "health": {
      "state": "disabled",
      "failure_kind": null,
      "consecutive_failures": 0,
      "suspended_until": null,
      "last_http_status": null,
      "last_failure_at": null
    }
  }
}

최초 연동

POST /api/v1/webhook/rotate-secret를 호출해 서명 비밀 키를 생성합니다. secret은 이 응답에서 한 번만 반환되므로 즉시 수신 측에 저장하세요. 초기화만으로는 콜백이 활성화되지 않습니다.
수신 측에서 아래 서명 검증을 설정합니다.
PATCH /api/v1/webhook으로 콜백 URL을 설정하고 enabled=true를 전달합니다. 처음 활성화하거나 URL을 바꾸면 endpoint.test 검증 이벤트가 생성되고 응답에 verification_event_id가 반환됩니다.
POST /api/v1/webhook/test로 테스트 이벤트를 보내거나 GET /api/v1/webhook/events/{event_id}로 검증·전달 결과를 확인합니다.

서명 검증

모든 콜백 요청에는 세 개의 헤더가 있습니다: X-ToAPIs-Webhook-Id (이벤트 ID), X-ToAPIs-Webhook-Timestamp (Unix 초 타임스탬프), X-ToAPIs-Webhook-Signature (서명).

검증할 때는 이벤트 ID, 타임스탬프, 원본 요청 본문을 .으로 이어 event_id.timestamp.raw_body를 만들고 저장한 secret으로 HMAC-SHA256을 계산해 서명 헤더의 v1= 뒤 16진 다이제스트와 비교합니다. 반드시 원본 요청 본문 바이트로 검증하고 JSON을 파싱해 다시 직렬화하지 마세요.

비밀 키 교체 기간에는 서명 헤더에 쉼표로 구분된 여러 v1= 값이 있을 수 있고 하나라도 일치하면 유효합니다. 수신 측은 이벤트 ID로 중복을 제거합니다. 콜백 payload와 서명 타임스탬프는 Unix 초이고 관리 API의 시각은 RFC 3339입니다.