EXIMBAY 개발자센터

구독 생성

POST/api/v1/partner/merchants/{merchantId}/webhooks

새로운 웹훅 구독을 생성합니다.

요청 파라미터

Path Parameters

merchantId string

필수

가맹점 ID입니다.

Request Body

endpointUrl string

필수

콜백 URL(HTTPS만 허용)입니다.

eventTypes array

필수

구독할 이벤트 타입 목록입니다.

요청

                            
{
"endpointUrl": "https://mysite.com/callback",
"eventTypes": ["PAYMENT_COMPLETED"]
}

응답 파라미터

id string

필수

웹훅 구독 ID입니다.

endpointUrl string

필수

콜백 URL입니다.

eventTypes array

필수

구독 이벤트 타입 목록입니다.

isActive boolean

필수

활성화 여부입니다.

createdAt string (ISO 8601)

필수

생성 일시입니다.

응답

                            
{
  "code": "CMN_0000",
  "message": "성공",
  "data": {
    "id": "wsub_abc123",
    "endpointUrl": "https://mysite.com/callback",
    "eventTypes": ["PAYMENT_COMPLETED"],
    "isActive": true,
    "createdAt": "2026-02-04T10:00:00"
  }
}

구독 목록 조회

GET/api/v1/partner/merchants/{merchantId}/webhooks

가맹점에 등록된 웹훅 구독 목록을 조회합니다.

요청 파라미터

Path Parameters

merchantId string

필수

가맹점 ID입니다.

요청

                            
curl -X GET https://link.eximbay.com/api/v1/partner/merchants/{merchantId}/webhooks \
-H "Authorization: Bearer eyJhbGciOi..."

응답 파라미터

id string

필수

웹훅 구독 ID입니다.

endpointUrl string

필수

콜백 URL입니다.

eventTypes array

필수

구독 이벤트 타입 목록입니다.

isActive boolean

필수

활성화 여부입니다.

createdAt string (ISO 8601)

필수

생성 일시입니다.

응답

                            
{
  "code": "CMN_0000",
  "data": [
    {
    "id": "wsub_abc123",
    "endpointUrl": "https://mysite.com/callback",
    "eventTypes": ["PAYMENT_COMPLETED"],
    "isActive": true,
    "createdAt": "2026-02-04T10:00:00"
    }
  ]
}

구독 수정

PUT/api/v1/partner/merchants/{merchantId}/webhooks/{publicId}

웹훅 설정을 수정합니다.

요청 파라미터

Path Parameters

merchantId string

필수

가맹점 ID입니다.

publicId string

필수

웹훅 구독 ID입니다.

Request Body

endpointUrl string

필수

콜백 URL(HTTPS만 허용)입니다.

eventTypes array

필수

구독할 이벤트 타입 목록입니다.

isActive boolean

활성화 여부입니다. 기본값은 true입니다.

요청

                            
{
  "endpointUrl": "https://mysite.com/new-callback",
  "eventTypes": ["PAYMENT_COMPLETED"],
  "isActive": true
}

응답 파라미터

id string

필수

웹훅 구독 ID입니다.

endpointUrl string

필수

콜백 URL입니다.

eventTypes array

필수

구독 이벤트 타입 목록입니다.

isActive boolean

필수

활성화 여부입니다.

createdAt string (ISO 8601)

필수

생성 일시입니다.

응답

                            
{
  "code": "CMN_0000",
  "message": "성공",
  "data": {
    "id": "wsub_abc123",
    "endpointUrl": "https://mysite.com/new-callback",
    "eventTypes": ["PAYMENT_COMPLETED"],
    "isActive": true,
    "createdAt": "2026-02-04T10:00:00"
  }
}

구독 삭제

DELETE/api/v1/partner/merchants/{merchantId}/webhooks/{publicId}

웹훅 구독을 삭제합니다.

요청 파라미터

Path Parameters

merchantId string

필수

가맹점 ID입니다.

publicId string

필수

웹훅 구독 ID입니다.

요청

                            
curl -X DELETE https://link.eximbay.com/api/v1/partner/merchants/{merchantId}/webhooks/{publicId} \
-H "Authorization: Bearer eyJhbGciOi..."

응답 파라미터

응답

                        
{
  "code": "CMN_0000",
  "message": "성공"
}

웹훅 페이로드

이벤트 발생 시 등록된 엔드포인트로 POST 요청이 전송됩니다.

공통 Envelope

id string

필수

이벤트 고유 ID(wevt_ prefix)입니다.

eventType string

필수

이벤트 타입입니다.

timestamp string(ISO 8601)

필수

이벤트 발생 시각 (UTC)입니다.

data object

필수

이벤트 데이터입니다. 타입별 구조는 아래 참고 바랍니다.

PAYMENT_COMPLETED

고객이 결제를 성공적으로 완료했을 때 발송됩니다.

invoice object* 인보이스 정보입니다.

invoiceId string

인보이스 ID입니다.

invoiceNumber string

인보이스 번호입니다.

status string

인보이스 상태입니다. (COMPLETED)

payment object* 결제 정보입니다.

transactionId string

PG 트랜잭션 ID입니다.

amount string

결제 금액입니다.

currency string

통화 코드입니다.

rescode string

통화 코드입니다. (0000 = 성공)

resmsg string

PG 응답 메시지입니다.

                            
{
  "id": "wevt_3aabc75328174dc4...",
  "eventType": "PAYMENT_COMPLETED",
  "timestamp": "2026-04-06T06:30:08.548Z",
  "data": {
    "invoice": {
      "invoiceId": "pinv_15b568b5cae4...",
      "invoiceNumber": "INV1ad8e89d9b2f",
      "status": "COMPLETED"
    },
    "payment": {
      "transactionId": "1A9D23DE54W000016...",
      "amount": "89000.00",
      "currency": "KRW",
      "rescode": "0000",
      "resmsg": "Success."
    }
  }
}