Webhook 이벤트 목록 | ToAPIs Documentation

GET

/api/v1/webhook/events

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

동작

Webhook 콜백의 전송 기록을 반환하여 도달 확인과 실패 원인 진단에 사용합니다. api_key_id를 생략하면 소속 전체 이벤트를 반환하고 지정하면 자신의 일반 모델 키인지 검증합니다 (소프트 삭제도 가능).

기본 범위는 최근 24시간, from/to는 쌍으로 필수이며 최대 31일, limit은 기본 50·최대 100으로 내부 ID 내림차순 페이지네이션입니다. 커서는 계정과 필터에 바인딩되므로 페이지 간 필터를 바꾸지 마세요.

이후 페이지에서 from/to를 생략하면 첫 페이지에서 정해진 범위를 그대로 사용하며, 페이지 요청 시점에 다시 계산하지 않습니다.

인증

Authorizationstring헤더필수

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

요청 매개변수

api_key_idinteger쿼리

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

task_idstring쿼리

플랫폼 작업 ID.

statusstring쿼리

전송 상태. pending/delivering/delivered/dead/cancelled.

fromstring쿼리

시간대가 있는 RFC 3339 시간. from/to 함께 지정.

tostring쿼리

시간대가 있는 RFC 3339 시간. from/to 함께 지정.

limitinteger쿼리

페이지 크기, 기본 50, 최대 100.

cursorstring쿼리

이전 페이지 커서.

파라미터가 유효하지 않으면 400, 필터링한 키가 없거나 타인 소유이면 404, 레이트 리밋 시 429입니다.

요청 예제

요청 예시

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

응답 예제

응답 예시

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "event_id": "evt_example",
        "api_key_id": 123,
        "task_id": "example-task",
        "type": "generation.completed",
        "status": "delivered",
        "attempts": 1,
        "reason": "delivered",
        "last_http_status": 200,
        "created_at": "2026-11-13T00:00:00Z",
        "next_attempt_at": null,
        "delivered_at": "2026-11-13T00:00:01Z",
        "expires_at": "2026-11-14T12:00:00Z"
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "scope": "self",
      "from": "2026-11-12T01:00:00Z",
      "to": "2026-11-13T01:00:00Z",
      "consistency": "eventual"
    }
  }
}

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