웹훅 가져오기

프로젝트 설정 페이지에서 결제 입금 알림을 보낼 주소를 구성할 수 있습니다.

웹훅을 전송할 때 다음과 같은 응답을 반환해야 합니다:

{
  "success": true
}

그렇지 않으면 서비스는 계속해서 웹훅을 재전송합니다. 최대 재시도 횟수는 30회입니다.

입금 웹훅 예시

{
  "amount": "2.395", - USD 기준 결제 금액
  "created_at": "2025-03-17T12:57:52.449795Z", - 결제 생성 시간
  "paid_at": "2025-03-17T12:57:19Z",- 결제 완료 시간
  "status": "completed", - 결제 상태
  "transactions": {
    "amount": "0.02552778", - 암호화폐 기준 결제 금액
    "amount_usd": "2.395", - USD 기준 결제 금액
    "bc_uniq_key": "0", - 트랜잭션 순번, BTC류 네트워크에서 중요; bc_uniq_key + tx_hash 조합으로 고유성 보장
    "blockchain": "litecoin", - 블록체인 이름
    "created_at": "2025-03-17T12:57:52.449795Z",- 결제 생성 시간
    "currency": "LTC", - 암호화폐 종류
    "currency_id": "LTC.Litecoin", - 암호화폐 식별자
    "tx_hash": "2be41b0cad76bc5699c3da5d5a1d390f9fb4038e5bfe49aec3b675f9dd4515fd", - 트랜잭션 해시
    "tx_id": "4bbc91fd-a950-4fd0-83f3-9f1c09a6b54f" - 상점에서의 트랜잭션 ID
  },
  "type": "PaymentReceived",  - 웹훅 타입
  "wallet": {
    "id": "9a07b545-f99e-4f51-bf37-a84fcbe4df4d", - 내부 사용자 ID
    "store_external_id": "1" - 외부 사용자 ID
  }
}

웹훅 수신 시 멱등성 검사

수신된 웹훅을 처리할 때 동일한 이벤트가 중복 처리되지 않도록 멱등성을 보장해야 합니다. 이를 위해 다음 두 필드를 사용해야 합니다:

tx_hash — 요청 또는 이벤트 내용의 해시;
bc_uniq_key — 웹훅 발신자가 제공한 고유한 이벤트 식별자.

웹훅을 처리하기 전에 hash와 uniq_key 조합이 이전에 처리되지 않았는지 확인해야 합니다. 이미 기록된 이벤트라면 중복으로 간주하고 무시해야 합니다.