인벤토리 시스템에서 게임 서버에 알림 전송(webhook)

개요

인벤토리 시스템에서 특정 서버에 알림을 전송하는 기능에 대한 가이드로 사전에 협의된 URL을 호출합니다.

• 개발사에서는 API를 수신하여 비즈니스 로직에 활용하시면 됩니다.

  • 필수 연동 사항은 아니므로 지원하는 알림 종류를 확인 후 필요 시 연동하시면 됩니다.

  • 연동을 희망하시는 경우 상세 가이드를 참고하여 API 개발 후 URL과 함께 기술 PM 등에게 요청하시면 됩니다.

• 사용 예) 유저가 유효한 쿠폰 사용 → 인벤토리 시스템은 쿠폰 사용 신규 아이템 수신 → 등록된 URL로 알림 전송 → 인벤토리 조회 API 호출하여 지급 아이템 확인 후 유저에게 뱃지 등으로 표현 가능

기본 정보

• 알림 시스템의 기본 데이터 포맷은 모든 알림에 공통으로 사용되며, 상세 필드(payload)에 알림의 세부 정보가 포함되는 형태입니다.

  • 즉, 하나의 API로 여러 알림을 통합해서 받으실 수 있습니다. (물론, 알림 종류별로 API를 다르게 구성해도 됩니다.)

• 인증방식은 기본 사설 도메인으로 연동하여 보안처리되지만, 필요 시 인증 헤더를 정의해서 제공해주셔도 됩니다.

• Content-Type은 application/json 으로 요청됩니다.

공통 데이터 포맷

• 모든 알림은 아래의 형식에 맞춰 요청합니다.

key	data type	required	description	example
notificationUuid	String	Y	알림마다 생성한 고유 아이디	21f4465a-12f6-45c0-b647-85ea942d8006
notificationType	String(50)	Y	알림 구분 코드	USER_COUPON_REDEEM_SUCCESS
payload	JsonObject	Y	알림 구분 코드에 해당하는 상세 정보	지원하는 알림 종류 별 payload example 참고

지원하는 알림 종류

notificationType	description	payload example
USER_COUPON_REDEEM_SUCCESS	쿠폰 시스템으로부터 쿠폰 아이템이 추가된 경우 알림 타입 유저가 유효한 쿠폰 사용 → 인벤토리 시스템은 쿠폰 사용 신규 아이템 수신 → 등록된 URL로 알림 전송 → 인벤토리 조회 API 호출하여 지급 아이템 확인 후 유저에게 뱃지 등으로 표현 가능	{ "rewardId": "a3546e4a-a4ef-4745-a994-c07cb2753aec", "userType": "GAME_CHARACTER_ID", "userValue": "98HUE3C2JVE4XGK6Q3SN" }

Request

HTTP Request end point에 대한 가이드

• /api/inventory/notification/ac6fmc4a 형태의 API URL을 정의

  • 특정 고정된 랜덤 스트링은 혹시 모르는 보안 사고를 막기 위해서 임의로 정해서 사용 추천

  • 해당 url 포맷은 예제이고 자유롭게 정의하셔도 좋습니다.

POST https://각 환경별 게임서버 도메인/api/inventory/notification/{특정한 고정된 랜덤 스트링}

알림 종류별 상세 정보(payload 필드) 파라미터

유저가 쿠폰 사용을 성공할 경우 알림

• 해당 알림의 notificationType은 USER_COUPON_REDEEM_SUCCESS입니다.

HTTP Request Parameter

key(1 depth)	key(2 depth)	type	required	description	example
payload		JsonObject	Y	알림의 상세정보
	rewardId	String(36)	Y	보상 아이템 고유 아이디	a3546e4a-a4ef-4745-a994-c07cb2753aec
	userType	String(20)	Y	userValue에 해당하는 ID 종류 IMID: HYBE IM의 id로 플랫폼 로그인 후 얻게되는 id, 정책상 기본적으로 인게임에서 유저가 보게되는 id value의 종류 GAME_UID: 게임쪽에서 자체 정의한 유저ID GAME_CHARACTER_ID: 게임쪽에서 자체 정의한 케릭터ID 기술PM 등과 사전에 협의된 값	IMID
	userValue	String(50)	Y	보상 아이템을 지급받은 userType에 해당하는 아이디	98HUE3C2JVE4XGK6Q3SN

요청 샘플 JSON (공통 데이터 포맷 포함)

{
  "notificationUuid": "21f4465a-12f6-45c0-b647-85ea942d8006",
  "notificationType": "USER_COUPON_REDEEM_SUCCESS",
  "payload": {
    "rewardId": "a3546e4a-a4ef-4745-a994-c07cb2753aec",
    "userType": "IMID",
    "userValue": "98HUE3C2JVE4XGK6Q3SN"
  }
}

Response

응답은 JSON형태로 전달됩니다.

Response property

Success Sample

• 수신 성공일 때는 resultCode에 SUCCESS로 입력 후 200 응답해주세요.

application/json;charset=UTF-8
{
    "resultCode": "SUCCESS",
    "resultMessage": "request success"
}

Error Sample

• 수신 후 처리 실패인 경우 HTTP 상태 코드는 200이지만 resultCode에 정의된 에러코드와 함께 참고할 수 있는 메시지를 resultMessage로 응답해주시면 됩니다.

• 게임쪽에서는 HTTP 상태 코드 관리에 어려운 경우가 많으셔서 상태 코드는 200으로 처리해주시면 됩니다.

{
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "not allow notificationType."
}

Error인 경우의 에러 코드 정의

• 아래의 에러 코드는 필수로 생각되어 미리 정의한 에러 코드입니다. 상황에 맞게 응답 해주시면 됩니다.

• 추가가 필요하면 코드 생성 후 공유주시면 추가 가능합니다.

에러 코드	비고
INVALID_PARAMETER	잘못된 파라미터로 알림 시스템에서의 요청 파라미터가 잘못된 경우
INTERNAL_SERVER_ERROR	게임서버 내부 정의되지 않은 오류(ex. 예외 발생 오류)
NOT_ALLOW_AUTH	API 사용 권한이 없는 경우 인증 정보가 잘못된 등 API 사용할 수 없는 요청인 경우