웹훅은 시스템에서 발생하는 이벤트에 대한 알림입니다. 특정 이벤트가 발생하면 엑솔라는 이벤트 데이터가 송신되는 HTTP 요청을 애플리케이션에 보냅니다. 이는 일반적으로 JSON 형식의 POST 요청입니다.
이벤트 예시:
설정한 이벤트가 발생하면 엑솔라는 웹훅을 통해 시스템에 해당 이벤트를 알립니다. 그 결과로 다음과 같은 작업을 수행할 수 있습니다.
결제 처리 웹훅 워크플로의 예시:
엑솔라 상품 및 솔루션으로 작업할 때의 웹훅 설정:
상품/솔루션 | 필수/선택 | 웹훅 사용처 |
---|---|---|
결제 | 필수 |
|
인게임 스토어 | 필수 |
|
Buy Button | 선택 사항 | 게임 키 판매의 경우 사용자 유효성 검사 및 아이템 추가가 필요하지 않습니다. 결제나 주문 취소 등 이벤트 관련 정보를 수신하기 위해 웹훅을 연결할 수 있습니다. 웹훅을 연결하는 경우 들어오는 모든 필수 웹훅을 처리해야 합니다. |
정기 결제 | 선택 사항 | 정기 결제 생성, 업데이트 또는 취소에 대한 정보를 받습니다. 또는 API를 통해 정보를 요청할 수 있습니다. |
웹샵 | 선택 사항 | 사용자 인증에 사용. 사용자 ID를 통한 인증을 사용하는 경우. 또는 엑솔라 로그인을 통한 사용자 인증을 사용할 수 있습니다. |
디지털 배포 솔루션 | 선택 사항 |
자세한 내용은 디지털 배포 솔루션용 웹훅 설정에 대한 지침에서 확인할 수 있습니다. |
웹훅이 필요한 제품 및 솔루션을 사용하는 경우 관리자 페이지에서 웹훅을 활성화 및 테스트하고 처리를 설정합니다. 특정 이벤트가 발생하면 웹훅이 순차적으로 전송됩니다. 따라서 웹훅 중 하나를 처리하지 않으면 후속 웹훅이 전송되지 않습니다. 필수 웹훅 목록은 아래와 같습니다.
인게임 스토어를 완벽하게 운영하려면 메인 웹훅의 처리를 구현해야 합니다.
user_validation
) - 사용자가 게임에 등록되었는지 확인하기 위해 결제 과정의 여러 단계에서 전송됩니다.payment
) - 주문이 결제될 때 전송되며 결제
데이터와 거래 세부 정보가 포함되어 있습니다.order_paid
) - 결제 웹훅이 성공적으로
처리되면 구매 아이템과 거래 ID에 대한 정보가 포함된 웹훅이 전송됩니다. 웹훅의 데이터를 사용하여 사용자에게 아이템을 추가합니다.refund
) - 주문이 취소될 때 전송되며 취소된 결제
데이터와 거래 세부 정보가 포함되어 있습니다.order_canceled
) -
환불 웹훅이 성공적으로 처리된 경우 전송되며 구매한 아이템에 대한
정보와 취소된 거래의 ID가 포함되어 있습니다. 웹훅의 데이터를 사용하여 구매한 아이템을 제거합니다.애플리케이션 측에 아이템 카탈로그 개인 설정이 구현된 경우 파트너 측에서 카탈로그 개인화 웹훅을 처리하도록 설정합니다.
참고
실제 결제를 받으려면 결제, 주문 결제 성공, 사용자 유효성 검증 웹훅 처리를 구현하고 라이선스 계약에 서명만 하면 됩니다.
정기 결제 플랜을 자동으로 관리하려면 기본 웹훅 처리를 구현해야 합니다.
user_validation
) - 사용자가 게임에 등록되었는지 확인하기 위해 결제 과정의 여러 단계에서 전송됩니다.payment
) - 주문이 결제될 때 전송되며 결제
데이터와 거래 세부 정보가 포함되어 있습니다.create_subscription
) - 결제
웹훅이 성공적으로 처리되었거나 사용자가 평가판 사용 기간이 있는 정기 결제 구매했을 때 전송됩니다. 여기에는 구매한 정기 결제의 세부 정보 및
사용자 데이터가 포함되어 있습니다. 웹훅 데이터를 사용하여 사용자에게 정기 결제를 추가할 수 있습니다.update_subscription
) - 정기 결제가 갱신되거나 변경될 때, 결제 웹훅이
성공적으로 처리되었을 때 전송됩니다. 여기에는 구매한 정기 결제의 세부 정보와 사용자 데이터가 포함되어 있습니다. 웹훅 데이터를 사용하여
사용자의 정기 결제를 연장하거나 정기 결제 매개 변수를 변경할 수 있습니다.refund
) - 주문이 취소될 때 전송되며 취소된 결제
데이터와 거래 세부 정보가 포함되어 있습니다.cancel_subscription
) - 환불 웹훅이
성공적으로 처리되었거나 다른 사유로 정기 결제가 취소된 경우 전송됩니다. 여기에는 정기 결제 및 사용자 데이터에 대한 정보가 포함되어
있습니다. 웹훅 데이터를 사용하여 구매한 정기 결제를 사용자로부터 제거합니다.웹훅 수신을 활성화하는 방법:
https://example.com
형식으로 지정합니다. 웹훅 테스트용
도구에서 찾은 URL을 지정할 수도 있습니다.주의
데이터 전송에는 HTTPS 프로토콜이 사용되며 HTTP 프로토콜은 지원되지 않습니다.
참고
웹훅을 테스트하려면 webhook.site와 같은 전용 웹사이트 또는 ngrok과 같은 플랫폼을 선택할 수 있습니다.
참고
웹훅을 동시에 다른 URL로 보낼 수 없습니다. 관리자 페이지에서 할 수 있는 작업은 먼저 테스트용 URL을 지정한 다음 실제 URL로 바꾸는 것입니다.
웹훅 수신을 비활성화하는 방법:
웹훅을 테스트하면 사용자 측과 엑솔라 측 모두에서 프로젝트를 올바르게 설정하는 데 도움이 돕니다.
다음 웹훅의 수신을 테스트할 수 있습니다.
웹훅 이름 | 웹훅 유형 |
---|---|
사용자 유효성 검사 | user_validation |
결제 | payment |
주문 취소 | order_canceled |
주문 결제 성공 | order_paid |
웹훅을 성공적으로 설정하면 웹훅 설정 섹션 아래에 웹훅 테스트 섹션이 표시됩니다.
참고
테스트 섹션에 테스트를 통과하지 못했다는 경고가 표시되면 웹훅 리스너에서 웹훅 응답 설정을 확인합니다. 테스트 오류의 원인은 테스트 결과에 표시됩니다.
예:
전문 사이트 webhook.site를 테스트에 사용합니다.
잘못된 서명에 대한 응답 테스트 섹션에 오류가 표시됩니다.
이는 엑솔라가 잘못된 서명이 포함된 웹훅을 전송하고 핸들러가 INVALID_SIGNATURE
오류 코드
4xx
HTTP 코드로 응답할 것으로 예상하기 때문에 발생합니다.
webhook.site는 잘못된 서명이 있는 웹훅을 포함하여 모든 웹훅에 응답으로 200
HTTP 코드를 전송합니다. 예상한 4xx
HTTP 코드를 구할 수 없으므로 테스트 결과에 오류가 표시됩니다.
스토어 탭에서 다음 웹훅을 테스트할 수 있습니다.
테스트 방법:
주문 결제 성공 및 주문 취소 웹훅은 지정된 데이터가 포함된 웹훅을 제공된 URL로 전송합니다. 각 웹훅 유형의 테스트 결과는 웹훅 테스트 버튼 아래에 표시됩니다.
결제 탭에서 다음 웹훅을 테스트할 수 있습니다.
user_validation
)payment
)테스트하는 방법:
지정된 URL로 데이터가 채워진 웹훅을 받게 됩니다. 성공한 시나리오와 오류가 있는 시나리오 모두에 대한 각 웹훅의 테스트 결과가 웹훅 테스트 버튼 아래에 표시됩니다. 프로젝트에 공개 사용자 ID가 활성화된 경우 사용자 검색 확인 결과도 표시됩니다.
각 웹훅에 대해 성공한 시나리오와 오류가 있는 시나리오를 모두 처리하도록 구성해야 합니다.
웹훅 서버 필드에 URL을 저장하면 웹훅에서 자세한 정보를 수신할 권한을 부여할 수 있는 고급 설정 섹션을 볼 수 있습니다. 이렇게 하려면 각 토글을 온으로 설정합니다. 각 권한의 줄에서 해당 설정의 영향을 받는 웹훅 목록을 확인할 수 있습니다.
토글 | 설명 |
---|---|
저장된 결제 계정에 대한 정보 표시 | 저장된 결제 방식에 대한 정보는 payment_account 사용자 정의 개체에서 전달됩니다. |
저장된 결제 방식을 사용한 거래에 대한 정보 표시 | 정보는 웹훅의 다음 사용자 정의 매개 변수에서 전달됩니다.
|
주문 개체를 웹훅에 추가 | 주문 관련 정보는 결제 웹훅의 order 개체에서 전달됩니다. |
민감한 데이터 없이 필수 사용자 매개 변수만 전송 | 사용자에 대한 다음 정보만 웹훅에서 전달됩니다.
|
사용자 정의 매개 변수 전송 | 사용자 정의 토큰 매개 변수 관련 정보가 웹훅에서 전달됩니다. |
카드 BIN 및 접미사 표시 | 은행 카드 번호에 대한 다음 정보가 웹훅에서 전달됩니다.
|
카드 브랜드 표시 | 결제에 사용된 카드의 브랜드. 예: Mastercard 또는 Visa. |
정기 결제 탭에서 다음 웹훅을 테스트할 수 있습니다.
user_validation
)payment
)참고
관리자 페이지에서는 기본 사용자 유효성 검사 및 결제 웹훅만 테스트할 수 있습니다. 다른 웹훅 유형을 테스트하려면 다음으로 이동합니다.
참고
웹훅을 테스트하려면 관리자 페이지 > 정기 결제 > 정기 결제 플랜 섹션에 하나 이상의 생성된 정기 결제가 있어야 합니다.
테스트하는 방법:
0
값을 지정합니다.지정된 URL로 데이터가 채워진 웹훅을 받게 됩니다. 성공적인 시나리오와 오류가 있는 시나리오 모두에 대한 각 웹훅의 테스트 결과가 웹훅 테스트 버튼 아래에 표시됩니다.
웹훅 리스너는 지정된 URL 주소로 들어오는 웹훅을 수신하고, 서명을 생성하며, 엑솔라 웹훅 서버로 응답을 전송하는 프로그램 코드입니다.
참고
웹훅 처리를 위한 기성 클래스가 포함된 페이 스테이션 PHP SDK 라이브러리를 사용할 수 있습니다.
애플리케이션 측에서 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 주소에서 웹훅을 수신하도록 구현합니다.
제한 사항:
웹훅을 수신할 때는 데이터 송신의 보안을 보장해야 합니다. 이를 위해 웹훅 데이터에서 서명을 생성하고 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"
}
}'
웹훅 수신을 확인하려면 서버가 다음을 반환해야 합니다.
200
, 201
또는 204
HTTP 코드.400
HTTP 코드. 서버에
일시적인 문제가 발생한 경우 웹훅 핸들러가 5xx
HTTP 코드를 반환할 수도 있습니다.주문 결제 성공 및 주문 취소 웹훅에 대한 응답이 수신되지 않았거나
5xx
코드가 포함된 응답이 수신된 경우 다음 일정에 따라 웹훅이 재전송됩니다.
웹훅 전송은 첫 번째 시도 후 12시간 이내에 최대 20번까지 시도할 수 있습니다. 결제 웹훅 또는 환불 웹훅에 대한 응답이 수신되지 않거나 '5xx' 코드가 포함된 응답이 수신되면 시간 간격을 늘려서 웹훅을 다시 보냅니다. 12시간 이내에 최대 12번까지 시도할 수 있습니다.
알림
엑솔라에서 결제 환불을 시작했고 환불 웹훅에 대해 `5xx` HTTP 코드가 포함된 응답을 받은 경우 결제 환불 처리가 계속됩니다.
사용자 유효성 검사 웹훅에 대한 응답을 받지
못했거나 400
또는 5xx
코드 응답을 받은 경우 사용자 유효성 검사 웹훅은 재전송되지 않습니다. 이 경우 사용자에게 오류가 표시되며 결제 및 주문 결제 성공 웹훅이 전송되지 않습니다.
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"
}
}
주의
알림 유형은 notification_type
매개변수로 전송됩니다.
웹훅 | 알림 유형 | 설명 |
---|---|---|
사용자 유효성 검사 | 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 |
상태가 비갱신으로 설정되면 보냅니다. |
결제 계정 추가 | payment_account_add |
사용자가 결제 계정을 추가하거나 저장할 때 보냅니다. |
결제 계정 제거 | payment_account_remove |
사용자가 저장된 계정에서 결제 계정을 제거할 때 보냅니다. |
웹 상점에서 사용자 유효성 검사 | - |
사용자가 게임에 존재하는지 확인하기 위해 웹 상점에서 전송됩니다. |
파트너 측의 카탈로그 개인 설정 | partner_side_catalog |
사용자가 스토어와 상호작용할 때 전송됩니다. |
주문 결제 성공 | order_paid |
주문이 결제되면 전송됩니다. |
주문 취소 | order_canceled |
주문이 취소되면 전송됩니다. |
분쟁 | dispute |
새로운 분쟁이 열리면 전송됩니다. |