웹훅 설정

웹훅은 시스템에서 발생하는 이벤트에 대한 알림입니다. 특정 이벤트가 발생하면 엑솔라는 이벤트 데이터가 전송되는 HTTP 요청을 애플리케이션으로 보냅니다. 이는 일반적으로 JSON 형식의 POST 요청입니다.

이벤트 예시:

• 아이템 카탈로그를 사용하는 사용자 상호 작용
• 결제 또는 주문 취소

웹훅 목록

인게임 스토어 및 결제 관리를 제대로 운영하려면 메인 웹훅 처리를 구현해야 합니다.

다음 구조는 결합된 웹훅을 사용하여 아이템을 구매하고 반품하는 절차를 보여줍니다.

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

아이템 카탈로그 개인 설정을 애플리케이션 측에서 구현한 경우 파트너 측에서 카탈로그 개인 설정 처리를 설정합니다.

관리자 페이지에서 웹훅 설정하기

수신 웹훅 활성화 방법:

1. 관리자 페이지의 프로젝트에서 설정 > 웹훅 섹션으로 이동합니다.
2. 웹훅 서버 필드에서 https://example.com 형식으로 웹훅을 수신할 서버 URL을 지정합니다. 웹훅 테스트용 도구에서 찾은 URL을 지정할 수도 있습니다.

3. 프로젝트 웹훅에 서명하기 위한 비밀 키가 기본적으로 생성됩니다. 새 비밀 키를 생성하려면 새로 고침 아이콘을 클릭합니다.
4. 웹훅 활성화를 클릭합니다.

웹훅 서버 필드에 URL을 저장하면 웹훅에서 자세한 정보를 수신할 권한을 부여할 수 있는 고급 설정 섹션을 볼 수 있습니다. 이렇게 하려면 필요한 토글을 활성화로 설정합니다. 각 권한의 줄에서 해당 설정의 영향을 받는 웹훅 목록을 확인할 수 있습니다.

1. 관리자 페이지의 프로젝트에서 설정 > 웹훅 섹션으로 이동합니다.
2. 웹훅 비활성화를 클릭합니다.

관리자 페이지에서 웹훅 테스트하기

프로젝트에서 웹훅을 활성화하면 고급 설정 아래에 웹훅 테스트 섹션이 관리자 페이지에 표시됩니다.

다음 웹훅을 테스트할 수 있습니다.

1. 웹훅 테스트 섹션에서, 결제 및 스토어 탭으로 이동합니다.
2. 드롭다운 메뉴에서 아이템 유형을 선택합니다. 선택한 아이템 유형이 프로젝트에 구성되지 않은 경우, 아이템 설정을 위한 버튼이 표시됩니다.
3. 필수 입력란을 채웁니다.
   • 엑솔라 주문 ID - 엑솔라 측의 주문 ID입니다. 테스트를 수행하는 경우 임의의 숫자 값을 사용할 수 있습니다.
   • 엑솔라 인보이스 ID - 엑솔라 측 거래 ID입니다. 테스트를 수행하는 경우 임의의 숫자 값을 사용할 수 있습니다.
   • 아이템 - 웹훅에서 정보를 수신하고자 하는 아이템입니다. 드롭다운 목록에서 아이템의 SKU를 선택하고 수량을 입력합니다. + 버튼을 클릭하여 새 행에 추가함으로써 동일한 유형의 여러 아이템을 선택할 수 있습니다.
   • 사용자 ID - 테스트를 수행하는 경우 임의의 문자 및 숫자를 사용할 수 있습니다.
   • 인보이스 ID - 게임 측의 거래 ID입니다. 테스트를 수행할 경우 임의의 문자와 숫자 조합을 사용할 수 있습니다. 이는 결제 성공을 위한 필수 매개 변수는 아니지만, 사용자 측 거래 ID를 엑솔라 측의 거래 ID와 연결하기 위해 전달할 수 있습니다.
   • 금액 - 결제 금액입니다. 테스트를 수행할 경우 임의의 숫자 값을 사용할 수 있습니다.
   • 통화 - 드롭다운 목록에서 통화를 선택하십시오.
4. 웹훅 테스트를 클릭합니다.

지정된 데이터가 포함된 주문 결제 성공, 주문 취소, 사용자 인증 웹훅이 제공된 URL로 전송됩니다. 각 웹훅 유형의 테스트 결과는 웹훅 테스트 버튼 아래에 표시됩니다. 각 웹훅에 대해 성공 시나리오와 오류 시나리오 모두에 대한 처리를 구성해야 합니다.

웹훅 수신기

웹훅 수신기는 지정된 URL 주소에서 들어오는 웹훅을 수신하고 서명을 생성한 후 엑솔라 웹훅 서버로 응답을 전송할 수 있는 프로그램 코드입니다.

서명 생성

웹훅을 수신할 때는 데이터 전송의 보안을 보장해야 합니다. 이를 위해서는 웹훅 데이터에서 서명을 생성하고 생성된 서명이 HTTP 요청 헤더에 전송된 서명과 일치하는지 확인해야 합니다.

서명 생성 방법:

1. 요청 본문과 프로젝트의 비밀 키의 JSON을 연결합니다.
2. 첫 번째 단계에서 구한 문자열에 SHA-1 암호화 해시 함수를 적용합니다.

웹훅으로 응답 보내기

웹훅 수신을 확인하려면 서버가 다음을 반환해야 합니다.

• 성공적인 응답의 경우 200, 201 또는 204 HTTP 코드
• 지정된 사용자를 찾을 수 없거나 잘못된 서명이 전달된 경우 문제 설명이 포함된 400 HTTP 코드

서버에 일시적인 문제가 발생한 경우 웹훅 핸들러가 5xx 코드를 반환할 수도 있습니다.

엑솔라 서버가 주문 결제 성공 및 주문 취소 웹훅에 대한 응답을 받지 못하거나 5xx 코드가 포함된 응답을 받은 경우, 다음 일정에 따라 웹훅이 다시 전송됩니다.

• 5분 간격으로 2번
• 15분 간격으로 7번
• 60분 간격으로 10번

웹훅 전송은 처음 시도 후 12시간 이내에 최대 20번까지 시도할 수 있습니다.

결제 및 환불 웹훅의 재시도 로직은 각 웹훅 페이지에 설명되어 있습니다.

엑솔라 서버가 사용자 유효성 검사 웹훅에 대한 응답을 받지 못하거나 400 또는 5xx 코드가 포함된 응답을 받은 경우, 사용자 유효성 검사 웹훅이 다시 전송되지 않습니다.

이 경우 사용자에게 오류가 표시되며 결제와 주문 결제 성공 웹훅은 전송되지 않습니다.

웹훅에서 아이템 정보 구성

items 배열을 통해 주문 결제 성공 및 주문 취소 웹훅에 포함할 아이템 데이터를 구성할 수 있습니다.

추가 매개 변수 포함 활성화

다음을 표시하는 추가 매개 변수의 포함 기능을 활성화하세요.

• 아이템이 무료인지 여부(is_free)
• 아이템이 보너스인지 여부(is_bonus)
• 아이템이 번들의 일부인지 여부(is_bundle_content)

이러한 매개 변수를 수신하려면 웹훅 설정에 대한 정보 업데이트 API 호출을 사용하여 웹훅을 버전 2로 전환해야 합니다. 버전 1(기본값)에서는 이러한 매개 변수를 사용할 수 없습니다.

추가 매개 변수가 있는 아이템 배열의 예시:

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

번들 콘텐츠 포함 비활성화

기본적으로 웹훅에는 번들의 모든 아이템이 개별 아이템 목록으로 포함됩니다. 콘텐츠를 나열하지 않고 번들 자체만 포함하도록 웹훅을 구성할 수 있습니다.

이 경우 번들에 포함된 아이템은 items 배열에 포함되지 않습니다. 위에 표시된 배열에서 번들의 일부인 SKU com.xsolla.gold_1가 있는 아이템은 제외됩니다.

번들 콘텐츠가 비활성화된 경우의 아이템 배열 예시:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

번들 콘텐츠 포함 기능을 비활성화하려면 고객 성공 관리자에게 문의하거나 csm@xsolla.com으로 이메일을 보내주세요.