Webhook 개요

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

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

반복해서 사용할 HTTPS 엔드포인트는 POST /webhooks로 등록합니다. Bank 충전 요청 하나에만 사용할 주소는 POST /request 본문의 callback_url에 HTTP 또는 HTTPS URL로 전달할 수 있습니다.

지원 이벤트

필드	타입	필수	제한	예시
`charge.approved` 충전 요청이 승인되었을 때	Bank	필수	—	—
`charge.rejected` 충전 요청이 거절되었을 때	Bank	필수	—	—
`payment.approved` Hosted Payment가 승인 완료되었을 때	Hosted Payment	필수	—	—
`payment.rejected` Hosted Payment 계좌이체가 거절되었을 때	Hosted Payment	필수	—	—

페이로드 구조

모든 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"
  }
}

전송 방식

충전 요청에 callback_url이 있으면 그 주소를 우선 사용합니다.
요청별 콜백이 없으면 같은 platform의 등록형 Webhook, 그다음 default Webhook 순서로 선택합니다.
엔드포인트가 2xx를 반환하면 전송 성공으로 처리합니다.
현재 버전은 자동 재시도 큐나 Webhook 전송 로그를 제공하지 않습니다.

시작하기

공개 수신 서버를 계속 운영한다면 등록형 Webhook을 사용하세요. 특정 충전 건의 결과만 받을 때는 요청별 callback_url을 사용하고, 전달이 누락됐는지는 GET /history/{id}로 확인할 수 있습니다.

이전이메일 제한 다음Webhook 요청 헤더