menu
Is this helpful?

# Webhook 연결 문서

# 1. 개요

TE 운영(Engage) 모듈의 Webhook은 사용자 메시지 또는 클래스 메시지 시스템과 연결하기 위한 API를 정의합니다. REST API 통합 개발을 통해 TE 운영 모듈에 내장되지 않은 트리거 채널을 신속하게 지원할 수 있습니다.

구체적인 호출 흐름은 아래 그림을 참조하십시오.

  1. 먼저, TE의 운영 모듈은 분석 모듈(Analytics)의 이벤트 데이터와 유저 데이터를 읽어와 대상 유저 세그먼트를 계산합니다.
  2. 대상 유저에게 맞추어 푸시 메시지 내용을 준비합니다. TE운영 모듈은, 설정한 Webhook 서비스에 HTTP 요청을 배치로 전송합니다.
  3. Webhook 서비스는 HTTP 호출을 수신하고, 요청 내용을 가져온 후 형식 변환 및 다른 비즈니스 데이터 결합 등의 선택적 작업을 수행하여 비동기 처리 큐에 넣을 수 있습니다. 그리고 마지막으로 내부 또는 외부 메시지/클래스 메시지 시스템을 호출할 수 있습니다.

[호출될 수 있는 시스템 예시] 1. 게임 내 메일(메시지) 시스템 1. 게임 내 공지 시스템 1. 계정 로그인 제한(Ban) 시스템 1. SMS 시스템 1. 서드파티 푸시 시스템

  1. 처리가 완료된 후(비동기 처리 플로우 제외), 요청 처리 결과를 지정된 형식으로 반환합니다. 처리에 실패한 데이터가 있는 경우, 해당 데이터의 일련번호와 실패 원인을 명시적으로 반환해야 합니다. TE 운영 모듈은 처리에 실패한 데이터를 기록합니다.
  2. 수신 확인 이벤트 데이터 수집(옵션)
    1. 게임 메일 시스템에 푸시할 경우, 유저가 게임 메일을 열 때 추적 데이터를 활성화하고 "메일 클릭"을 푸시 클릭으로 추적하여 관련 투명 파라미터도 지정하여 보다 정확한 도달 단계의 퍼널 분석을 실현할 수 있습니다.

# 2. Webhook 서비스

TE 운영 모듈과의 커스텀 채널 연결을 위해 HTTP Endpoint Server를 개발해야 합니다. 아래에 제시된 API 정의를 따라야 합니다.

# 2.1 입력/출력 형식 정의

# Webhook 요청

서비스의 입력 파라미터는 TE 운영 모듈에서 구축되어 POST 메서드로 전송됩니다. Content-Type은 application/json으로 설정됩니다. 요청 본문 request_body는 JSONArray이며, 여러 메시지 데이터를 일괄적으로 전송할 수 있습니다. 각 메시지 데이터는 특정 내용을 가진 한 명의 유저에게 메시지를 전송하는 것을 나타냅니다.

DANGER

주의 TE 운영 모듈의 Webhook은 하나의 요청 내용에 여러 유저의 트리거 메시지를 포함합니다. 이는 하향식 시스템이 대량 처리를 용이하게 하고 송신 효율을 향상시키기 위한 것입니다. 한 배치에 포함된 유저 수는 커스텀 설정에 따라 다릅니다.

파라미터 예시：

// 요청의 입력 데이터 형식
[
{"push_id":"accountid123987001","custom_params"{"gameuid":"123acb001","name":"TA",...},"params":{"title":"데일리 이벤트",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
,{"push_id":"accountid123987002","custom_params":{"gameuid":"123acb002","name":"TE",...},"params":{"title":"데일리 이벤",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
]

// 각 메시지의 입력 파라미터 형식
{
//채널의 발신 ID는 일반적으로 유저의 고유 ID이며, 계정 ID 또는 롤 ID 등입니다. 운영 담당자가 "운영-운영 설정-채널"에서 정의합니다.
    "push_id": "accountid123987001",
    
//템플릿 파라미터, 이 파라미터의 구체적인 내용은, 「운영-운영 설정-채널」에서 정의할 수 있습니다.
"params": {
    "title": "데일리 이벤트",
    "content": "안녕하세요! 일일 미션을 빨리 완료합시다!",
    // 객체 그룹
    "attachment": [
        {
            "item_id":"xx1",
            "count":"5"
        },
        {
            "item_id":"xx2",
            "count":"10"
        }
    ]
},

// 커스텀 파라미터는 유저 속성을 추출할 수 있습니다. 이 파라미터의 구체적인 내용은 "운영-운영 설정-채널"에서 정의할 수 있습니다.
 "custom_params": {
     "zone_id":"17281",
     "name": "TE"
},

// 채널 수신 확인 속성, 이 파라미터는 운영 모듈에 의해 기본으로 추가되며 후속 데이터 분석에 사용됩니다. 일반적으로 비즈니스 측에서는 분석할 필요가 없으므로 하향 시스템으로 투과적으로 전송하십시오. 하향 시스템으로 전송할 때 이 JSON 객체를 직접 보내고 toString()을 사용하지 않도록 주의하십시오.
"#ops_receipt_properties": {   
    "ops_project_id": 1,  // TE의 프로젝트 ID
    "ops_task_id": "0050", // 운영 태스크 ID
    "ops_task_instance_id": "0050_2023-01-01",  // 운영 태스크 인스턴스
    "ops_task_exec_detail_id": "17795",  // 운영 태스크 인스턴스의 푸시
    "ops_request_id": "f7b66eb7-3363-4a46-a402-601a64b45f76", // 하나의 배치 요청에 대응하여 같은 요청 내의 모든 ops_request_id가 동일합니다. 또한 요청이 다시 시도되어도 이 ID는 변경되지 않습니다. 게임 시스템이 요청을 이중성으로 검증해야 하는 경우 이 필드를 사용할 수 있습니다.
    "ops_push_language": "default",  // 운영 태스크의 푸시 언어
    "ops_exp_group_id": "122" // 운영 태스크의 AB 테스트 그룹 ID
}

파라미터

유형

필수

의미

비고

push_id

String

Yes

푸시 ID

 특정 파라미터 필드는 '운영-운영설정-채널-Push ID'에서 정의할 수 있습니다.

params

Object

No

템플릿 파라미터

 운영 측에서 입력해야 하는 몇 가지 채널 파라미터, 예를 들어 푸시 컨텐츠에 관한 것입니다.

custom_params

Object

No

커스텀 파라미터

 자동으로 추출되는 푸시 대상 유저의 속성입니다.

#ops_receipt_properties

Object

Yes

수신 확인 필드

 TE 운영 모듈에서 자동으로 추가됩니다. 하향 시스템이 메시지 클릭 상태를 관찰해야 할 경우, 이 필드를 직접 투과하여 전송해야 합니다. 변환 이벤트가 설정되어 있으면 이 필드를 전송할 필요가 없습니다.
> 템플릿 파라미터와 커스텀 파라미터의 키 네이밍 규칙: 언더스코어로 구분하여 명명하며, 파라미터는 영/숫자와 언더스코어로 이루어져 있으며, 첫 글자는 언더스코어와 영문자만 가능합니다. > 주의: params와 custom_params의 파라미터에서는 모든 데이터 유형(정수, 소수, 날짜 등)에 대해 요청을 전송할 때 모든 필드가 문자열로 변환되도록 처리됩니다.

# Webhook 응답

{
    "return_code": 0,
    "return_message": "success",
    "data": {
    
// fail_list의 각 요소는 실패한 객체의 정보이며, 에러 메시지와 에러 객체 번호가 포함되어 있습니다. 에러 객체 번호는 1부터 시작합니다. 예를 들어, 5개의 객체 정보를 전송하고, 번호가 1부터 5인 경우를 가정합니다. 3개가 성공하고 2개가 실패했다고 가정하면, 두 번째와 네 번째가 실패한 경우 다음과 같이 반환됩니다.
        "fail_list": [{
            "index": 2
            "message": "푸시할 필요가 있는 토큰 정보가 존재하지 않습니다."
        }, {
            "index": 4
            "message": "push id not found",
        }]
    }
}

파라미터

타입

필수

설명

return_code

Integer

Yes

 반환 값: 0 성공(또는 일부 성공) 1 실패

return_message

String

No

 응답 정보

data

Object

No

 응답 데이터

data.fail_list

Array

No

 return_code가 0인 경우, data.fail_list가 [] 또는 null이면 전체가 성공으로 간주됩니다. data.fail_list가 비어 있지 않으면 일부 실패로 간주되며, 실패에 대한 자세한 내용이 목록에 정의됩니다. 비즈니스 측에서 일부분의 실패 상황이 존재하지 않는 경우, 단순히 []를 전달하십시오.

주의 사항:

  1. 일부 사용할 수 없는 PushId의 유효성 검사는 연결 처리 로직의 전반부에서 수행하는 것이 좋습니다. 이렇게 함으로써, fail_list를 반환하여 TE에 전달함으로써 작업의 트리거 성공 지표 통계가 더 정확해집니다.
  2. 실패 목록의 객체의 index 속성은 번호로 표시됩니다. 번호는 1부터 시작하며 0이 아닙니다!
  3. message 필드는 필수가 아니지만 반환하는 것이 강력히 권장됩니다. 이렇게 함으로써 비정상 시에 문제 해결이 용이해집니다.

return_code가 1인 경우, data.fail_list에 무엇이 전달되었는지와 관계없이 모두 실패로 간주됩니다.

# 2.2 요청 인증

인증 기능은 기본적으로 비활성화되어 있습니다.

Webhook의 경우 서버가 인증을 필요로하지 않는 경우, 이 섹션을 건너 뛰십시오.

인증을 지원하는 경우, Webhook 설정 시 인증 스위치를 켜야합니다. 송신 측은 HTTP 요청 헤더에 서명을 추가합니다. 키는 X-TE-OPS-Signature입니다. 서버 측에서는 비밀 키와 요청 본문을 사용하여 HmacSHA1 서명을 생성하고, 서명을 송신 측의 서명과 비교합니다. 일치하는 경우 인증이 통과된 것입니다.

서명 알고리즘의 Java 구현 참고:

import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
/*
HmacSHA1 서명 알고리즘
secretKey는 고객이 설정한 비밀 키입니다.
requestBody는 요청 내용의 JSONString입니다.
*/
public static String HmacSHA1(String secretKey,String requestBody) throws Exception {
    String signature = (new HmacUtils(HmacAlgorithms.HMAC_SHA_1,secretKey)).hmacHex(requestBody)
    return signature;
}

PHP에서의 서명 알고리즘 구현 참고:

/**
* HmacSHA1 서명 알고리즘
* @param $secretKey : 설정된 비밀 키
* @param $requestBody : 요청 내용의 JSONString
* @return string 서명 값
*/
function HmacSHA1($secretKey, $requestBody) {
    return hash_hmac('sha1', $requestBody, $secretKey);
}

# 2.3 요청 병렬성 성능

메시지의 전송 속도를 보장하기 위해, 카스텀 채널 서비스가 지원하는 병렬성이 높을수록 좋습니다. 100개 이상의 TPS를 지원하는 것이 좋습니다. 동시에, TE 엔게이지 모듈은 하향 카스텀 채널 서비스의 병렬성 성능 상한에 따라 적절한 제한 설정이 가능합니다.

# 2.4 요청과 결과의 전체 테스트 예

// 요청
curl -X POST "http://localhost:8999/v1/カスタムチャネル/test/sample"
-H "accept: /"
-H "X-TE-OPS-Signature: 2e1ee1eeaDA121"
-H "Content-Type: application/json"
-d "[{"push_id":"3e156c91-f039-4d48-9b6f-72b76111af24","custom_params":{"name":"티키"},"params":{"title":"데일리 이벤트","content":"안녕하세요 티키님, 일일 미션을 빨리 완료합시다!"},"#ops_receipt_properties":{"ops_task_id":"0050","ops_request_id":"f7b66eb7-3363-4a46-a402-601a64b45f76","ops_task_instance_id":"31","ops_project_id":1}}]"
// 응답

{
  "data": {
      "fail_list": []
  },
  "return_code": 0,
  "return_message": "success"
}

# 3. Webhook의 설정 가능한 파라미터

다음 파라미터는 기본적으로 백엔드에 설정되어 있습니다. 변경이 필요한 경우, 당사 직원에게 문의하십시오.

구성 항목

설정 가능 값

기본값

구성 설명

전송 제한

-1, [1,10000]

제한 없음

  • 단위: 회/초

  • -1로 설정할 경우, 제한이 없습니다.

  • 1-10000의 수치를 설정할 경우, 예를 들어 500으로 설정하면, 1초당 최대 500회의 요청을 받을 수 있는 하위 Webhook 서버를 나타냅니다.

배치 크기

[1,500]

100

  • JsonArray에 포함된 엘리먼트의 수를 나타냅니다.

  • 배치 크기를 크게 설정하면, 메시지 전송 효율이 향상됩니다.

  • 배치 크기를 작게 설정하면, 전송 속도는 느려지지만, 신뢰성이 높아집니다.

  • 권장 값은 100이며, 최대값은 500입니다.

타임아웃 시간

[0,600]

60

  • 단위: 초

  • HTTP 요청의 소켓 타임아웃 시간은 기본적으로 60초입니다.

  • 설정이 <=0일 경우, 타임아웃이 발생하지 않습니다.

실패 재시도 횟수

[0,10]

0
  • 중복된 비즈니스 푸시를 피하기 위해, 기본적으로 0회, 즉 재시도하지 않도록 설정되어 있습니다.
    • 0 값이 설정된 경우, 인터페이스의 타임아웃이나 인터페이스의 return_code!=0이 반환될 때 재시도 로직이 실행됩니다.

재시도 간격 시간

[0,600]

5

  • 단위: 초

  • 기본적으로 5초마다 한 번 재시도합니다.

반환값의 엄격 검증

On / Off

ON

  • ON으로 설정하면, TE 오퍼레이션 모듈 서비스는 하류 서버가 반환하는 response의 형식을 검증합니다. 위의 Webhook response 파라미터 정의 규격에 부합하지 않는 경우, 실패로 간주됩니다.

  • 예: 타임아웃 시간을 5초로 설정하고, 반환값의 엄격 검증을 활성화하지 않은 경우, Webhook 서비스는 5초 이내에 정상적으로 반환되며, 반환값은 HTTP 200이고, Body가 없는 경우, TE 엔게이지 모듈에서는 이 호출을 성공으로 간주합니다.

  • 반환값의 엄격 검증을 활성화한 경우, Webhook 서비스는 5초 이내에 정상적으로 반환되고, 반환값이 HTTP 200이지만, 본문이 없거나 본문의 형식과 규약이 일치하지 않는 경우, TE 운영 모듈에서는 호출 실패로 간주됩니다.

#

# 4. 커스텀 채널 생성

예시

구성 항목

설명

비고

채널명

커스텀 채널의 이름 (표시, 선택용)

 유일성 검증 필요

채널 URL

메시지 푸시 수신 인터페이스의 URL

 같은 URL 주소로 여러 채널을 설정 가능

전송 ID

메시지의 수신 대상 유저 ID. 예를 들어, 메일 전송 시, 유저의 캐릭터 ID(role_id)

 전송 ID는 유저 속성에 저장해야 함 예상 인원 수를 계산할 때는 전송 ID가 없는 유저는 제외됨

채널 검증

Webhook 채널의 인증 방법

 기본값은 OFF, 필요 시 ON 설정

퍼널 설정

채널 관련 원본 이벤트 이름

 옵션으로 활성화 가능

컨텐츠 템플릿

채널이 유저에게 전송하는 구체적인 내용의 템플릿은 텍스트, 동적 텍스트, 숫자, 오브젝트 그룹 등의 필드 타입을 지원합니다. 예를 들어, 메일 전송 채널에서는 오브젝트 그룹 타입을 사용하여 아이템의 내용(아이템 ID와 아이템 수)을 구성할 수 있습니다. 이는 타게팅 태스크의 프론트엔드 페이지에 표시되며, 운영 태스크를 구성하는 운영 담당자가 입력할 수 있습니다.

 필드: 파라미터의 이름, 메시지 본문에서 전송될 때 사용됩니다. 필드명: 태스크 생성 시 표시되는 필드 필드 타입: 텍스트, 동적 텍스트, 숫자, 오브젝트 그룹 등 힌트 문구: 태스크 생성 시 입력 필드의 힌트(필수 아님) 필수 여부: yes/no (단일 선택, 기본값은 'yes')

커스텀 파라미터

채널의 요구사항에 따라 선택적으로 추가됩니다. 이 파라미터는 투명하게 사용됩니다.

 필수가 아님

필드: 파라미터의 이름, 메시지 본문에서 전송될 때 사용됩니다. 관련 필드: 필드에 관련된 유저 속성, 메시지 본문을 전송할 때, 이 속성 값이 기본값으로 사용됩니다. 옵션이지만, 기본값이 설정되어 있고, 속성 값이 비어 있을 경우 기본값이 사용됩니다. 기본값이 설정되어 있지 않을 경우, 속성 값이 비어 있을 경우 빈 값을 반환합니다.

# 5. 푸시 클릭 이벤트 수집

커스텀 채널에서 발송된 메시지를 활용하여, 필요에 따라 클라이언트/서버 상에서 클릭 이벤트를 수집할 수 있습니다. 수집 방법은 TE의 데이터 액세스 가이드의 '이벤트 전송'을 참조하시기 바랍니다. 이벤트 이름은 사용자가 커스텀할 수 있습니다. 이벤트 데이터는 커스텀 채널에서 발송된 메시지의 #ops_receipt_properties 필드를 가져와서 객체 속성로 묶어 전송하면 됩니다. 다른 분석 시나리오가 있는 경우, 이 이벤트에 다른 필드 속성를 추가할 수도 있습니다.

주의: 속성 필드명은 반드시 #ops_receipt_properties이어야 하며, 데이터 타입은 객체입니다. 임의로 변경할 수 없습니다. 필드명을 변경하거나, 필드 내부의 내용을 변경하거나, 필드를 텍스트 속성로 잘못 전송하는 경우, 후속 데이터 사용에 이상이 발생할 가능성이 있습니다.

코드 예시：

JSONObject properties = new JSONObject();
// 커스텀 채널에서 발송된 메시지 본문에서 JSON 구조의 ops_receipt_properties 객체를 가져와서, 그것을 객체의 속성로 전송합니다.
JSONObject opsReceiptProperties = message.get("#ops_receipt_properties");
// 속성명은 반드시 ops_receipt_properties이며, 변경할 수 없습니다. 이벤트명은 커스텀할 수 있습니다.
properties.put("#ops_receipt_properties", opsReceiptProperties);
// properties 객체 내용 예: "#ops_receipt_properties":{"ops_task_id":"0062","ops_project_id":2,"ops_task_instance_id":"62","ops_request_id":"967ea854-2c42-490b-9c33-c1792ea637ec"}
instance.track("ops_push_click", properties);

← 프리셋 App Push 구현 가이드 →