웹훅을 사용하면 엑솔라에서 발생하는 구성된 이벤트에 대해 빠르게 알림을 받을 수 있습니다. 웹훅을 사용하여 애플리케이션의 백엔드 및 추가 기능을 자동화할 수 있습니다.

알림을 받을 수 있는 이벤트의 예:

• 게임머니 및 아이템 구매를 포함한 결제
• 정기 결제 및 구독 작업
• 환불

구성된 이벤트가 발생하면 엑솔라가 웹훅을 통해 시스템에 알립니다. 예를 들어, 웹훅을 수신한 후 다음을 수행할 수 있습니다:

• 사용자의 잔액에 추가
• 새 아이템 잠금 해제
• 구독 서비스 시작
• 부정결제 감지 후 게임유저를 차단합니다

결제 처리 웹훅이 작동하는 방식은 다음과 같습니다.

웹훅이 제대로 작동하려면 다음 설정을 적용해야 합니다:

• 다음 IP 주소의 웹훅을 수락해야 합니다: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.
• 애플리케이션 데이터베이스에 동일한 ID의 트랜잭션이 중복 되어서는 안됩니다.

• 생성된 서명이 HTTP 헤더에서 통과된 서명과 동일해야 합니다.
• 오류가 발생한 경우, 코드 400을 반환합니다(예: 필수 매개 변수 누락, 결제 실패). 코드 500은 일시적 서버 오류를 나타냅니다.

인터넷 연결이 항상 100% 신뢰할 수 있는 것은 아니므로, 웹훅이 소실되거나 지연될 수 있습니다. 이 문제를 해결하기 위해 엑솔라는 수신기에서 웹훅을 수신할 때까지 실패한 웹훅을 다시 보냅니다. 웹훅 재전송은 수신기에서 수신을 확인할 때까지 이전 전송 후 12시간 이내에 전송됩니다. 최대 재시도 횟수는 12회입니다.

전자 서명은 데이터 전송에 보안을 제공합니다. 서명을 생성하려면:

1. 요청의 JSON 콘텐츠와 프로젝트 시크릿 키를 연결합니다.
2. 결과 문자열에 SHA-1 해싱을 적용합니다.

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

HTTP 코드 400에 대한 오류 코드:

코드	메시지
INVALID_USER	잘못된 게임유저
INVALID_PARAMETER	잘못된 매개변수
INVALID_SIGNATURE	잘못된 서명
INCORRECT_AMOUNT	잘못된 금액
INCORRECT_INVOICE	잘못된 인보이스

HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

웹훅	제품/솔루션	알림 유형	설명
게임유저 유효성 검사	페이 스테이션	user_validation	게임 시스템 내 유저의 존재를 확인하기 위해 보냅니다.
사용자 검색	페이 스테이션	user_search	공개 사용자 ID별로 사용자 정보를 가져오기 위해 보냅니다.
결제	페이 스테이션, 구독	payment	유저가 결제 프로세스를 완료했을 때 보냅니다.
환불	페이 스테이션, 구독	refund	알 수 없는 이유로 결제가 취소되었을 때 보냅니다.
부분 환불	페이 스테이션	partial_refund	어떤 이유로든 결제를 부분적으로 취소해야 할 때 전송됩니다.
AFS 거부 거래	페이 스테이션	afs_reject	AFS 확인 중에 거래가 거부된 경우 보냅니다.
AFS 업데이트된 차단 목록	페이 스테이션	afs_black_list	AFS 차단 목록이 업데이트될 때 보냅니다.
정기 결제 생성	정기 결제	create_subscription	유저가 정기 결제를 만들면 보냅니다.
업데이트된 정기 결제	정기 결제	update_subscription	정기 결제가 갱신되거나 변경되었을 때 보냅니다.
취소된 정기 결제	정기 결제	cancel_subscription	정기 결제가 취소되었을 때 보냅니다.
비갱신 정기 결제	정기 결제	non_renewal_subscription	상태가 비갱신으로 설정되면 보냅니다.
게임 키 가져오기	Buy Button	get_pincode	엑솔라 API가 게임 키를 얻어야 하는 경우 보냅니다.
게임유저 잔액: 수동 업데이트	인게임 스토어	user_balance_operation	게임유저 잔액을 직접 변경할 필요가 있을 경우 보냅니다. 작업 유형 — internal.
게임유저 잔액: 결제	인게임 스토어	user_balance_operation	게임유저가 결제를 진행한 경우 보냅니다. 작업 유형 — payment.
게임유저 잔액: 환불	인게임 스토어	user_balance_operation	사용자가 결제를 취소할 때 전송됩니다. 작업 유형 — cancellation.
게임유저 잔액: 쿠폰 사용	인게임 스토어	user_balance_operation	게임유저가 게임에서 쿠폰을 사용하여 아이템이나 게임머니를 구매할 경우 보냅니다. 작업 유형 — coupon.
게임유저 잔액: 구매	인게임 스토어	user_balance_operation	게임유저가 게임 내에서 구매할 때 보냅니다. 작업 유형 — inGamePurchase.
키 활성화	Buy Button	redeem_key	사용자가 키를 활성화하면 보냅니다.
결제 계정 추가	페이 스테이션	payment_account_add	사용자가 결제 계정을 추가하거나 저장할 때 보냅니다.
결제 계정 제거	페이 스테이션	payment_account_remove	사용자가 저장된 계정에서 결제 계정을 제거할 때 보냅니다.
웹 상점에서 사용자 유효성 검사	웹 상점	-	사용자가 게임에 존재하는지 확인하기 위해 웹 상점에서 전송됩니다.
지불 거래 처리	결제 금액	-	지불 거래가 생성되어 처리 중임을 알리기 위해 전송됩니다.
지불 거래 완료	결제 금액	-	지불 거래가 성공적으로 완료되었음을 알리기 위해 전송됩니다.
파트너 측의 카탈로그 개인 설정	인게임 스토어	partner_side_catalog	사용자가 스토어와 상호작용할 때 전송됩니다.
주문 결제 성공	인게임 스토어	order_paid	주문이 결제되면 전송됩니다.
주문 취소	인게임 스토어	order_canceled	주문이 취소되면 전송됩니다.