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

이벤트 예시:

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

설정한 이벤트가 발생하면 엑솔라는 웹훅을 통해 시스템에 해당 이벤트를 알립니다. 그 결과로 다음과 같은 작업을 수행할 수 있습니다.

• 사용자의 잔액 충전
• 결제 대금 환불
• 사용자 계정에서 새 아이템 추가 또는 제거
• 정기 결제 서비스 제공 시작
• 부정 결제가 의심되는 경우 사용자 차단

결제 처리 웹훅 워크플로의 예시:

엑솔라 웹훅 통합을 위한 동영상 가이드:

엑솔라 상품 및 솔루션으로 작업 시 웹훅 설정:

웹훅 작업이 필요한 상품 및 솔루션을 사용하는 경우 관리자 페이지에서 웹훅을 활성화 및 테스트하고 처리를 설정합니다. 특정 이벤트가 발생하면 웹훅이 순차적으로 전송됩니다. 따라서 웹훅 중 하나를 처리하지 않으면 후속 웹훅이 전송되지 않습니다. 필수 웹훅 목록은 아래에 제시되어 있습니다.

사이트에서 아이템을 구매하고 반품할 때 엑솔라 측에서 2개의 웹훅 전송 옵션이 설정되었습니다. 결제 및 트랜잭션 데이터가 포함된 정보와 구매한 아이템에 대한 정보는 별도로 제공되거나 하나의 웹훅으로 결합될 수 있습니다.

결합된 웹훅에서 정보 수신:

2025년 1월 22일 이후 관리자 페이지에 등록한 경우, 주문 결제 성공(order_paid) 및 주문 취소(order_canceled) 웹훅의 모든 정보를 수신하게 됩니다. 이 경우, 결제(payment) 및 환불(refund) 웹훅을 처리하지 않아도 됩니다.

개별 웹훅에서 정보 수신:

2025년 1월 22일 이후 관리자 페이지에 등록한 경우, 다음 웹훅을 받게 됩니다.

• 결제 데이터 및 트랜잭션 세부 정보가 포함된 결제(payment) 및 환불(refund).
• 구매한 아이템에 대한 정보가 포함된 주문 결제 성공(order_paid) 및 주문 취소(order_canceled).

유입되는 모든 웹훅을 처리해야 합니다. 결합된 웹훅을 수신하는 새로운 옵션으로 전환하려면 고객 성공 관리자에게 문의하거나 csm@xsolla.com으로 이메일을 보내십시오.

인게임 스토어와 결제 관리를 완벽하게 운영하려면 주요 웹훅을 처리해야 합니다.

결합된 웹훅을 수신하는 경우:

개별 웹훅을 수신하는 경우:

애플리케이션 측에 아이템 카탈로그 개인 설정이 구현된 경우 파트너 측에서 카탈로그 개인화 웹훅을 처리하도록 설정합니다.

정기 결제 플랜을 자동으로 관리하려면 기본 웹훅 처리를 구현해야 합니다.

• 사용자 유효성 검사(user_validation) - 사용자가 게임에 등록되었는지 확인하기 위해 결제 과정의 여러 단계에서 전송됩니다.
• 결제(payment) - 주문이 결제될 때 전송되며 결제 데이터와 트랜잭션 세부 정보가 포함되어 있습니다.
• 생성된 정기 결제(create_subscription) - 결제 웹훅이 성공적으로 처리되었거나 사용자가 평가판 사용 기간이 있는 정기 결제 구매했을 때 전송됩니다. 여기에는 구매한 정기 결제의 세부 정보 및 사용자 데이터가 포함되어 있습니다. 웹훅 데이터를 사용하여 사용자에게 정기 결제를 추가할 수 있습니다.
• 업데이트된 정기 결제(update_subscription) - 정기 결제가 갱신되거나 변경될 때, 결제 웹훅이 성공적으로 처리되었을 때 전송됩니다. 여기에는 구매한 정기 결제의 세부 정보와 사용자 데이터가 포함되어 있습니다. 웹훅 데이터를 사용하여 사용자의 정기 결제를 연장하거나 정기 결제 매개 변수를 변경할 수 있습니다.
• 환불(refund) - 주문이 취소될 때 전송되며 취소된 결제 데이터와 트랜잭션 세부 정보가 포함되어 있습니다.
• 취소된 정기 결제(cancel_subscription) - 환불 웹훅이 성공적으로 처리되었거나 다른 사유로 정기 결제가 취소된 경우 전송됩니다. 여기에는 정기 결제 및 사용자 데이터에 대한 정보가 포함되어 있습니다. 웹훅 데이터를 사용하여 구매한 정기 결제를 사용자로부터 제거합니다.

웹훅 수신을 활성화하는 방법:

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

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

웹훅 수신을 비활성화하는 방법:

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

웹훅의 경우 결제 및 스토어 섹션에서 고급 설정을 사용할 수 있습니다. 이러한 설정은 자동으로 웹훅 수신 버튼을 클릭한 후 일반 설정 블록 아래에 나타납니다.

이 섹션에서는 웹훅에서 추가 정보 수신을 설정할 수 있습니다. 이를 위해 해당 스위치를 활성 위치로 설정합니다. 각 권한의 줄은 설정을 변경하면 영향을 받는 웹훅을 나타냅니다.

웹훅을 테스트하면 사용자 측과 엑솔라 측 모두에서 프로젝트를 올바르게 설정하는 데 도움이 돕니다.

웹훅을 성공적으로 설정하면 웹훅 설정 섹션 아래에 웹훅 테스트 섹션이 표시됩니다.

관리자 페이지의 테스트 섹션은 웹훅 수신 옵션에 따라 다릅니다.

결합된 웹훅을 수신하는 경우:

개별 웹훅을 수신하는 경우:

결합된 웹훅이 있는 시나리오를 테스트하는 프로세스는 아래와 같습니다.

결제 및 스토어 탭에서 다음 웹훅을 테스트할 수 있습니다.

• 사용자 유효성 검사(user_validation)
• 주문 결제 성공(order_paid)
• 주문 취소(order_canceled)

테스트 방법:

1. 웹훅 테스트 섹션에서 결제 및 스토어 탭으로 이동합니다.

2. 드롭다운 메뉴에서 아이템 유형을 선택합니다. 선택한 유형의 아이템이 관리자 페이지에 설정되어 있지 않으면 다음을 클릭합니다.

   • 연결 - 이 유형의 아이템이 있는 모듈이 연결되어 있지 않은 경우
   • 구성 - 이전에 모듈을 연결했지만 설정을 완료하지 않은 경우
     버튼을 클릭하면 선택한 아이템의 유형에 해당하는 관리자 페이지 섹션으로 리디렉션됩니다. 아이템을 생성한 후 웹훅 테스트 섹션으로 돌아가 다음 단계를 진행합니다.

3. 필수 입력란을 채우세요.

   1. 드롭다운 목록에서 아이템의 SKU를 선택하고 금액을 표시합니다. +를 클릭하고 새 줄에 추가하여 동일한 유형의 아이템을 여러 개 선택할 수 있습니다.
   2. 사용자 ID - 테스트 시 문자와 숫자의 조합을 사용할 수 있습니다.
   3. 공개 사용자 ID - 이메일이나 닉네임 등 사용자에게 알려진 ID. 이 필드는 페이 스테이션 > 설정의 프로젝트에서 공개 사용자 ID가 활성화된 경우 표시됩니다.
   4. 엑솔라 주문 ID 필드에 값을 입력합니다.
   5. 엑솔라 인보이스 ID - 엑솔라 측 트랜잭션 ID. 테스트 시 숫자 값을 사용할 수 있습니다.
   6. 인보이스 ID - 게임 측의 트랜잭션 ID. 테스트 시 문자와 숫자의 조합을 자유롭게 사용할 수 있습니다. 성공적인 결제를 위한 필수 매개 변수는 아니지만, 사용자 측의 트랜잭션 ID를 엑솔라 측의 트랜잭션 ID에 연결하기 위해 전달할 수 있습니다.
   7. 금액 - 결제 금액. 테스트할 시 어떤 숫자든 사용할 수 있습니다.
   8. 통화
      • 드롭다운 목록에서 통화를 선택합니다.

4. 웹훅 테스트를 클릭합니다.

사용자 유효성 검사, 주문 결제 성공 및 주문 취소 웹훅은 지정된 데이터가 포함된 웹훅을 제공된 URL로 전송합니다. 각 웹훅 유형의 테스트 결과는 웹훅 테스트 버튼 아래에 표시됩니다.

프로젝트에서 공개 사용자 ID가 활성화된 경우 사용자 검색 검사 결과도 볼 수 있습니다.

각 웹훅에 대해 성공한 시나리오와 오류가 있는 시나리오를 모두 처리하도록 구성해야 합니다.

정기 결제 탭에서 다음 웹훅을 테스트할 수 있습니다.

• 사용자 유효성 검사(user_validation)
• 결제 (payment)

테스트하는 방법:

1. 테스트 섹션에서 정기 결제 탭으로 이동합니다.
2. 필수 입력 필드에 값을 입력합니다.
   1. 사용자 ID - 테스트 시 문자와 숫자의 조합을 사용할 수 있습니다.
   2. 엑솔라 인보이스 ID - 엑솔라 측의 트랜잭션 ID입니다. 테스트 시 숫자 값을 사용할 수 있습니다.
   3. 공개 사용자 ID - 사용자에게 알려진 ID(예: 이메일 또는 닉네임). 이 필드는 페이 스테이션 > 설정 > 추가 설정 섹션의 프로젝트에서 공개 사용자 ID가 활성화된 경우에 표시됩니다.
   4. 통화 - 드롭다운 목록에서 통화를 선택합니다.
   5. 플랜 ID - 정기 결제 플랜입니다. 드롭다운 목록에서 플랜을 선택합니다.
   6. 정기 결제 상품 - 드롭다운 목록에서 상품을 선택합니다(선택 사항).
   7. 금액 - 결제 금액입니다. 테스트할 때는 아무 숫자나 사용할 수 있습니다.
   8. 인보이스 ID - 게임 측의 트랜잭션 ID입니다. 테스트할 때 문자와 숫자를 조합하여 사용할 수 있습니다. 성공적인 결제를 위한 필수 매개 변수는 아니지만 트랜잭션 ID를 엑솔라 측과 연결하기 위해 전달할 수 있습니다.
   9. 평가 기간. 평가 기간 없이 정기 결제 구매를 테스트하거나 정기 결제 갱신을 테스트하려면 0 값을 지정합니다.
3. 웹훅 테스트를 클릭합니다.

지정된 URL로 데이터가 채워진 웹훅을 받게 됩니다. 성공적인 시나리오와 오류가 있는 시나리오 모두에 대한 각 웹훅의 테스트 결과가 웹훅 테스트 버튼 아래에 표시됩니다.

웹훅 리스너는 지정된 URL 주소로 들어오는 웹훅을 수신하고, 서명을 생성하며, 엑솔라 웹훅 서버로 응답을 전송하는 프로그램 코드입니다.

애플리케이션 측에서 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24, 34.102.38.178, 34.94.43.207, 35.236.73.234, 34.94.69.44, 34.102.22.197 IP 주소에서 웹훅을 수신하도록 구현합니다.

제한 사항:

• 애플리케이션의 데이터베이스에 동일한 ID로 성공한 트랜잭션이 있으면 안 됩니다.
• 웹훅 리스너가 데이터베이스에 이미 존재하는 ID로 웹훅을 수신한 경우 이 트랜잭션의 이전 처리 결과를 반환해야 합니다. 사용자에게 중복 구매 항목을 추가하고 데이터베이스에 중복 레코드를 생성하는 것은 좋지 않습니다.

안전하게 데이터를 전송하려면 웹훅이 실제로 엑솔라 서버에서 전송되었는지 확인하세요. 이를 위해 요청 본문을 기반으로 서명을 생성하고 동일한 요청의 Authorization 헤더에 있는 서명과 비교합니다.

서명 생성 방법:

1. 요청 본문을 JSON 형식으로 검색합니다.
2. 문자열 끝에 비밀 키를 추가하여 JSON 문자열을 프로젝트의 비밀 키와 연결합니다.
3. 결과 문자열에 HMAC-SHA1 암호화 해시 함수를 적용합니다.
4. 결과를 소문자 16진수 문자열로 변환합니다.
5. 결과 문자열을 Authorization HTTP 요청의 헤더 서명과 비교합니다.

웹훅(HTTP) 예시:

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"
      }
    }'

서명 생성을 위한 C# 예시:

private string ComputeHmacSha1(string jsonBody, string secretKey)
{
    // Concatenation of the JSON from the request body and the project’s secret key.
    string dataToSign = jsonBody + secretKey;
    using var hmac = new HMACSHA1(Encoding.UTF8.GetBytes(secretKey));
    byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
    return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
}

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

• 성공적인 응답의 경우 200, 201 또는 204 HTTP 코드.
• 지정한 사용자를 찾을 수 없거나 잘못된 서명이 전달된 경우 문제 설명이 포함된 400 HTTP 코드. 서버에 일시적인 문제가 발생한 경우 웹훅 핸들러가 5xx HTTP 코드를 반환할 수도 있습니다.

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

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

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

엑솔라 서버가 결제 웹훅 또는 환불 웹훅에 대한 응답을 수신하지 않았거나 '5xx' 코드가 포함된 응답을 수신한 경우 시간 간격을 늘려서 웹훅을 다시 보냅니다. 12시간 이내에 최대 12번까지 시도할 수 있습니다.

엑솔라 서버가 사용자 유효성 검사 웹훅에 대한 응답을 수신하지 않았거나 400 또는 5xx 코드가 있는 응답을 수신한 경우 사용자 유효성 검사 웹훅은 재전송되지 않습니다. 이 경우 사용자에게 오류가 표시되며 결제 및 주문 결제 성공 웹훅이 전송되지 않습니다.

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

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