Webhook 등록

충전 상태 변경과 Hosted Payment 완료 이벤트를 수신할 Webhook 엔드포인트를 등록합니다.

POSThttps://bank.apiacc.com/webhooks

등록 시 서명 검증에 사용할 webhook_secret이 한 번만 반환됩니다. 안전하게 보관하세요.

요청 본문

필드	타입	필수	제한	예시
`platform` Webhook을 찾을 때 사용하는 라우팅 키입니다. 생략하면 `default`로 등록됩니다. Bank 이벤트는 충전 요청의 `platform`과 같은 Webhook을 먼저 찾고, 없으면 `default` Webhook으로 전송합니다. Hosted Payment는 `default` Webhook을 사용합니다.	string	선택	—	"default"
`url` 이벤트를 수신할 HTTPS 엔드포인트입니다. 운영 환경에서는 공개 HTTPS URL만 허용됩니다.	string	필수	—	"https://my-service.com/webhooks/apiacc"

curl -X POST "https://bank.apiacc.com/webhooks" \
  -H "Authorization: Bearer $BANK_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 10 \
  -d '{
    "platform": "default",
    "url": "https://my-service.com/webhooks/apiacc"
  }'

응답

201Webhook 생성 성공

{
  "webhook": {
    "id": "wh_abc123",
    "platform": "default",
    "url": "https://my-service.com/webhooks/apiacc",
    "created_at": "2026-08-15T03:20:00Z"
  },
  "webhook_secret": "whsec_5f8a1c9b3d7e4f2a",
  "warning": "webhook_secret is shown once"
}

webhook_secret은 이 응답에서만 확인할 수 있습니다

생성 응답의 최상위 필드로 내려오는 webhook_secret 값은 다시 조회할 수 없습니다. 유실 시 Webhook을 삭제하고 다시 등록해야 합니다.

충전 요청과 Webhook 등록은 별개입니다

충전 요청을 생성한다고 Webhook이나 secret이 자동으로 만들어지지 않습니다. 이벤트를 받으려면 먼저 이 엔드포인트로 Webhook을 등록하세요.

주요 오류

상태	error
400	invalid_platform
400	invalid_webhook_url
500	webhook_create_failed
429	rate_limit_exceeded

이전Webhook 목록 다음Webhook 삭제