Webhook 개요

계좌 입금과 Hosted Payment 완료 같은 비동기 이벤트를 실시간으로 수신하는 방법을 소개합니다.

Webhook은 apiacc에서 발생한 이벤트를 등록한 HTTPS 엔드포인트로 즉시 전송하는 방식입니다. 폴링 없이 상태 변경을 실시간으로 처리할 수 있습니다.

Webhook은 충전 요청이나 결제 생성 요청만으로 자동 생성되지 않습니다. 먼저 POST /webhooks로 수신 URL을 등록하고, 생성 응답에서 내려오는 webhook_secret을 저장해야 합니다.

지원 이벤트

페이로드 구조

모든 Webhook 이벤트는 아래와 같은 공통 구조를 가집니다.

{
  "id": "evt_9f8e7d6c",
  "type": "charge.approved",
  "created_at": "2026-08-15T03:01:13Z",
  "data": {
    "charge_id": "chg_example123",
    "amount": 10000,
    "platform": "default",
    "ref": "order_1234",
    "status": "approved"
  }
}

전송 방식

• 등록된 Webhook이 없으면 이벤트는 전송되지 않고 API 응답의 Webhook 상태가 disabled로 표시될 수 있습니다.
• 엔드포인트가 2xx를 반환하면 전송 성공으로 처리합니다.
• 현재 버전은 자동 재시도 큐나 Webhook 전송 로그를 제공하지 않습니다.