Webhook 전송 테스트 | ToAPIs Documentation

POST

/api/v1/webhook/test

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

동작

저장된 콜백 URL로 endpoint.test 이벤트를 하나 보내 수신 측의 서명 검증과 응답을 확인합니다. 전송은 비동기입니다: HTTP 202와 반환된 event_id는 큐 등록만을 의미하고 도달을 뜻하지 않습니다. 전송 결과는 이벤트 상세 API로 확인하세요.

테스트는 저장된 URL만 사용할 수 있고 임시 URL이나 사용자 지정 payload는 불가합니다. mode=off이거나 전역 전송이 일시 중지되면 409를 반환합니다.

삭제되거나 scope 가 있는 Key 는 수정할 수 없습니다. 비활성, 만료, 잔액 소진 모델 Key 도 관리할 수 있습니다. 속도 제한은 키 수명주기 쓰기와 공유되며, 사용자당 분당 최대 10회의 쓰기 요청만 허용됩니다.

JSON 최대 16384 바이트, 본문 읽기 제한 10 초이며 쿼리 매개변수, 알 수 없거나 중복된 JSON 필드를 거부합니다. Api_key_id 를 명시해야 합니다.

인증

Authorizationstring헤더필수

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

요청 매개변수

api_key_idinteger본문필수

본인 일반 모델 Key 의 양의 정수 ID 이며 sk- 비밀 키나 액세스 토큰이 아닙니다. JSON 에서는 정수만 허용하며 문자열, null, 생략, 쿼리 매개변수는 거부합니다.

api_key_id가 유효하지 않으면 400, 대상 키가 없거나 타인 소유이면 404, 설정 미저장·불완전이거나 테스트가 금지된 경우 409 (code=16015/16016), 레이트 리밋 시 429입니다.

요청 예제

요청 예시

curl --request POST \
  --url 'https://api.toapis.com/api/v1/webhook/test' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"api_key_id":123}'

응답 예제

응답 예시

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "event_id": "evt_example"
  }
}

초기 설정 순서와 서명 검증은 Webhook 설정 조회를 참조하세요.