본문으로 건너뛰기

Webhook 채널 연동 문서

최근 업데이트 2026. 10. 05.

1. 소개​

AE 운영 모듈의 Webhook 채널은 다운스트림 고객 측의 모든 메시지 또는 유사 메시지 시스템과 연결하기 위한 API를 정의합니다. 고객은 비교적 가벼운 REST API 연동 개발만으로 AE 운영 모듈에 내장되지 않은 푸시 채널을 빠르게 지원할 수 있습니다. 구체적인 호출 흐름은 다음 그림을 참고하십시오:

  1. 먼저 AE 운영 모듈(Engage)은 AE 플랫폼의 이벤트 데이터와 유저 데이터를 사용하여 목표 타겟을 계산합니다.
  2. 목표 타겟을 바탕으로 메시지 내용을 구성합니다. AE 운영 모듈은 설정된 webhook 채널 서비스로 HTTP 요청을 배치로 나누어 보냅니다.
  3. 자체 webhook 채널 서비스는 http 호출을 수신하여 요청 내용을 가져온 후 형식 변환, 다른 비즈니스 데이터 결합, 비동기 처리 큐 투입 등의 작업을 직접 수행할 수 있으며, 최종적으로 다른 내부 또는 외부의 메시지/유사 메시지 시스템을 호출합니다. 호출할 수 있는 시스템의 예는 다음과 같습니다:
  • 게임 우편 시스템
  • 게임 공지 시스템
  • 계정 정지 시스템
  • SMS 시스템
  • 서드파티 푸시 시스템
  1. 처리가 완료되면(비동기 처리 과정 제외) 약속된 형식에 따라 이번 요청의 처리 결과를 반환합니다. 처리에 실패한 데이터가 있으면 해당 데이터의 번호와 실패 원인을 명확히 반환해야 합니다. AE 운영 모듈은 처리에 실패한 데이터를 기록합니다.
  2. 회신 이벤트 데이터 회수(선택)
  • 게임 우편 시스템으로 푸시하는 경우, 유저가 게임 우편을 열 때 트래킹을 설정하여 "우편 클릭"을 푸시 클릭 트래킹 이벤트로 삼고 약속에 따라 관련 패스스루 파라미터를 포함하면, 도달 단계의 퍼널 분석을 더 정확하게 할 수 있습니다.

2. Webhook 채널 서비스​

AE 운영 모듈의 Webhook 채널과 연동하려면 HTTP Endpoint Server를 개발해야 합니다. 이 서버가 따라야 할 API 정의는 아래를 참고하십시오.

2.1 입력·출력 파라미터 형식 정의​

Webhook 채널 Request​

서비스의 입력 파라미터는 AE 운영 모듈에서 생성하며, POST 방식을 사용하고 Content-Type은 application/json으로 설정합니다. 요청 본문 request_body는 JSONArray이며, 한 배치에 여러 메시지 데이터를 보낼 수 있습니다. 각 메시지 데이터는 유저 한 명에게 특정 내용의 메시지 하나를 보내는 것을 나타냅니다.

팁

주의: AE 운영 모듈의 Webhook 채널은 하나의 요청 본문에 여러 유저의 트리거 메시지를 포함합니다. 이는 다운스트림에서 일괄 처리하기 쉽게 하여 발송 효율을 높이기 위한 것입니다. 한 배치에 포함되는 유저 수는 커스텀 설정할 수 있습니다.

파라미터 예시는 다음과 같습니다:

// 요청 입력 파라미터 형식
[
    {"push_id":"accountid123987001","custom_params":{"gameuid":"123acb001","name":"홍길동",...},"params":{"title":"일일 이벤트",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
    ,{"push_id":"accountid123987002","custom_params":{"gameuid":"123acb002","name":"김철수",...},"params":{"title":"일일 이벤트",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
]

// 각 메시지의 구체적인 입력 파라미터 형식
{
    //채널의 전송 id로, 일반적으로 유저 고유 id(예: 계정 id 또는 캐릭터 id)입니다. 운영 담당자가 'AE 운영 모듈-채널 관리'에서 정의합니다
    "push_id": "accountid123987001",
    
    //템플릿 파라미터. 이 파라미터의 구체적인 파라미터 내용은 'AE 운영 모듈-채널 관리'에서 정의할 수 있습니다
    "params": {
        "title": "일일 이벤트",
        "content": "안녕하세요 홍길동 님, 지금 바로 이벤트에 참여하세요!",
        //객체 그룹
        "attachment": [
            {
                "item_id":"xx1",
                "count":"5"
            },
            {
                "item_id":"xx2",
                "count":"10"
            }
        ]
    },
    //커스텀 파라미터. 유저 속성을 가져올 수 있으며, 이 파라미터의 구체적인 파라미터 내용은 'AE 운영 모듈-채널 관리'에서 정의할 수 있습니다
     "custom_params": {
         "zone_id":"17281",
         "name": "홍길동"
    },
    //채널 회신 속성. 이 파라미터는 AE 운영 모듈 시스템에서 기본으로 추가하며 이후 데이터 통계에 사용됩니다. 일반적으로 비즈니스 측에서 파싱할 필요 없이 다운스트림으로 그대로 전달하면 됩니다. 다운스트림에서 전송할 때는 이 json 객체를 그대로 전송하고, toString한 후 전송하지 마십시오
    "#ops_receipt_properties": {   
        "ops_project_id": 1,  //AE 프로젝트 id에 대응
        "ops_task_id": "0050", //운영 작업 하나에 대응하며, 운영 작업으로 푸시할 때만 포함
        "ops_task_instance_id": "0050_2023-01-01",  //운영 작업 인스턴스 1회에 대응하며, 운영 작업으로 푸시할 때만 포함
        "ops_task_exec_detail_id": "17795",  //작업 인스턴스의 푸시 1회에 대응하며, 운영 작업으로 푸시할 때만 포함
        "ops_request_id": "f7b66eb7-3363-4a46-a402-601a64b45f76", //푸시 1회 중 batch 요청 1회에 대응합니다. 같은 요청 안의 모든 ops_request_id는 동일하며, 요청을 재시도해도 이 ID는 변경되지 않습니다. 고객 비즈니스 시스템에서 요청의 멱등성을 검증하려면 이 필드를 사용할 수 있습니다. 운영 작업으로 푸시할 때만 포함됩니다.
        "ops_exp_group_id": "122", //운영 작업의 AB 실험 그룹 id에 대응하며, 운영 작업에서 AB 실험을 활성화한 경우에만 포함
        "ops_flow_id":"0050", //플로우 캔버스 하나에 대응하며, 플로우 캔버스 액션 노드에서 배포할 때만 포함
        "ops_flow_version":"V_20251010_1", //플로우 캔버스 버전 번호이며, 플로우 캔버스 액션 노드에서 배포할 때만 포함
        "ops_node_id":"1001", //플로우 캔버스 노드 ID이며, 플로우 캔버스 액션 노드에서 배포할 때만 포함
        "ops_push_language": "default"  //푸시 언어에 대응하며, 다국어로 푸시할 때 포함
       
    }
}
파라미터 이름파라미터 타입필수 여부파라미터 설명비고
push_idString예푸시 ID구체적인 파라미터 필드는 운영 설정-채널 관리-전송 ID에서 정의할 수 있습니다
paramsObject아니요템플릿 파라미터푸시할 때 운영 담당자가 입력해야 하는 일부 채널 파라미터(예: 푸시 내용)입니다. 구체적인 파라미터 내용은 운영 설정-채널 관리-컨텐츠 템플릿에서 정의할 수 있습니다
custom_paramsObject아니요커스텀 파라미터시스템에서 자동으로 가져와야 하는 푸시 대상 유저의 유저 속성입니다. 구체적인 파라미터 내용은 운영 설정-채널 관리-커스텀 파라미터에서 정의할 수 있습니다
#ops_receipt_propertiesObject예AE 운영 모듈 회신 필드AE 운영 모듈 시스템에서 기본으로 추가합니다. 다운스트림 시스템에서 메시지의 클릭 현황을 확인해야 하는 경우 클릭 이벤트에서 이 필드를 그대로 전달하여 전송해야 합니다. 작업 목표 설정의 전환 이벤트에는 이 필드를 전송할 필요가 없습니다

템플릿 파라미터, 커스텀 파라미터의 Key 명명 규칙: 밑줄로 구분하여 명명하며, 파라미터는 영문자, 숫자, 밑줄로 구성하고 첫 글자는 밑줄 또는 영문자만 사용할 수 있습니다. 주의: params와 custom_params의 파라미터에서 모든 타입의 데이터(정수, 소수, 날짜 등)는 요청을 보낼 때 모든 필드를 문자열로 변환하여 처리합니다

Webhook 채널 Response​

파라미터 예시는 다음과 같습니다:

{
    "return_code": 0,
    "return_message": "success",
    "data": {
        // fail_list의 각 요소는 실패한 객체 정보이며, 오류 메시지와 오류 객체의 번호를 포함합니다. 오류 객체 번호는 1부터 시작합니다. 예: 객체 정보 5개를 보내 번호가 1-5이고 3개 성공, 2개 실패이며 그중 2번째와 4번째가 실패한 경우 다음과 같이 반환합니다
        "fail_list": [{
            "index": 2,
            "message": "푸시할 플레이어의 token 정보가 없습니다"
        }, {
            "index": 4,
            "message": "push id not found"
        }]
    }
}
파라미터 이름파라미터 타입필수 여부파라미터 설명
return_codeInteger예반환 코드 0은 성공(또는 일부 성공), 1은 실패를 의미합니다
return_messageString아니요반환 정보
dataObject아니요반환 데이터
data.fail_listArray아니요

return_code=0인 경우,

  • data.fail_list가 [] 또는 null이면 전체 성공으로 간주합니다
  • data.fail_list가 비어 있지 않으면 일부 실패이며, 실패 상세 정보는 list에 정의된 내용입니다.
  • 비즈니스상 일부 실패가 발생하지 않는 경우 []를 그대로 전달하면 됩니다. 주의:
  1. 사용할 수 없는 PushId 검증은 API 처리 로직에서 사전 검증을 수행하여 fail_list에 담아 AE로 반환하는 것을 권장합니다. 이렇게 하면 작업의 푸시 성공 지표 통계가 더 정확해집니다.
  2. 실패 목록에 있는 객체의 index 속성은 번호를 나타내며, 번호는 1부터 시작합니다. 0부터 시작하는 것이 아닙니다!
  3. message 필드는 필수는 아니지만, 오류 발생 시 문제를 쉽게 해결할 수 있도록 반환할 것을 강력히 권장합니다.

return_code=1인 경우 data.fail_list에 무엇을 전달하든 전체 실패로 간주합니다.

2.2 요청 인증​

이 단계의 설정을 마친 후 Webhook 채널 제품 화면에서 활성화할 수 있습니다.

인증 기능은 기본적으로 비활성화되어 있습니다. Webhook 채널 server에 인증이 필요하지 않으면 이 부분을 건너뛰어도 됩니다. 인증을 지원하려면 채널을 설정할 때 채널 검증 스위치를 켜야 합니다. 그러면 발송 측에서 서명을 http 요청 헤더에 추가하며, Key는 X-TE-OPS-Signature입니다. 서버 측에서는 키와 Request Body로 HmacSHA1 서명을 수행하여 signature를 생성한 다음 발송 측의 서명과 비교해야 하며, 일치하면 인증에 성공한 것입니다. 서명 알고리즘의 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 요청 동시성 성능​

메시지 푸시 속도를 보장하려면 Webhook 채널 서비스가 지원하는 동시성이 높을수록 좋으며, 100 TPS 이상을 지원하는 것을 권장합니다. 또한 AE의 운영 모듈은 다운스트림 Webhook 채널 서비스의 동시 처리 능력 상한에 맞춰 속도 제한을 설정할 수 있습니다.

2.4 요청 및 결과 전체 테스트 예시​

// 요청 정보
curl -X POST "http://localhost:8999/v1/webhook_channel/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 채널 설정 가능 파라미터 소개​

다음 파라미터는 기본적으로 백엔드에서 설정합니다. 수정이 필요하면 ThinkingAI 고객 성공팀에 문의하십시오

구성 항목선택 가능한 값기본값설정 설명
발송 속도 제한-1，[1,10000]속도 제한 없음단위: 회/초. -1로 설정하면 속도를 제한하지 않습니다. 1-10000 사이의 숫자(예: 500)로 설정하면 다운스트림 Webhook 채널 서버로 초당 최대 500회의 요청을 보낸다는 의미입니다.
발송 배치 크기[1,500]1001회 호출 파라미터의 JsonArray에 포함되는 요소 수를 나타냅니다. 배치 크기를 크게 설정하면 메시지 발송 효율을 높일 수 있습니다. 배치 크기를 작게 설정하면 발송 속도는 느려지지만 신뢰성은 더 높아집니다. 권장 설정 값은 100이며, 최대 500까지 설정할 수 있습니다.
타임아웃 시간[0,3600]60단위: 초. http 요청 socket 타임아웃 시간이며, 기본값은 60s입니다. <=0으로 설정하면 타임아웃이 없는 것과 같습니다.
실패 재시도 횟수[0,10]0비즈니스상 중복 푸시를 피하기 위해 기본값은 0회, 즉 재시도하지 않습니다. >0 값을 설정하면 API 타임아웃 또는 API가 return_code!=0을 반환할 때 재시도 로직이 실행됩니다.
실패 재시도 시간 간격[0,600]5단위: 초. 기본적으로 5s마다 한 번 재시도합니다.
반환 값 강력 검증활성화, 비활성화활성화활성화하면 AE 운영 모듈 서비스가 다운스트림 서버가 반환한 response의 형식을 검증하며, 위의 Webhook 채널 response 파라미터 정의 규칙에 맞지 않으면 실패로 간주합니다. 예: 타임아웃 시간을 5s로 설정했다고 가정합니다. 반환 값 강력 검증을 활성화하지 않은 경우 Webhook 채널 서비스가 5s 이내에 정상적으로 반환하고 반환 값이 Body 없는 HTTP 200이면 AE 운영 모듈은 이번 호출을 성공으로 간주합니다. 반환 값 강력 검증을 활성화한 경우 Webhook 채널 서비스가 5s 이내에 정상적으로 반환하더라도 반환 값이 Body 없는 HTTP 200이거나 Body 형식이 약속된 규칙과 다르면 AE 운영 모듈은 이번 호출을 실패로 간주합니다.

4. 채널 설정 페이지 예시​

파라미터설명비고
채널 이름Webhook 채널의 이름(표시 및 선택에 사용)고유성 검증
URL메시지 푸시를 수신하는 API 주소같은 URL 주소로 여러 채널을 설정할 수 있음
전송 ID메시지를 받는 타겟 유저의 ID 타입입니다. 예를 들어 우편을 발송할 때는 유저의 캐릭터 ID(role_id)를 사용합니다전송 ID는 유저 속성으로 전송해야 합니다. 타겟 유저 인원 예측 시 전송 ID가 비어 있는 유저는 제외됩니다
사용자 지정 헤더요청을 보낼 때 추가하는 사용자 지정 HTTP 요청 헤더로, Authorization, API Key 또는 비즈니스 식별자를 전달하는 데 사용합니다기본적으로 비활성화되어 있으며, 필요에 따라 활성화할 수 있음. 최대 10개이며, 헤더 이름은 대소문자를 구분하지 않음
채널 검증커스텀 채널 인증 방식기본적으로 비활성화되어 있으며, 필요에 따라 활성화할 수 있음
도달 퍼널 설정퍼널 단계에 연결된 이벤트 이름선택적으로 활성화
컨텐츠 템플릿해당 채널이 유저에게 보내는 구체적인 내용의 템플릿으로, 텍스트, 동적 텍스트, 숫자, 객체 그룹 등의 필드 타입을 지원합니다. 예를 들어 우편 발송 채널에서는 객체 그룹 타입으로 아이템 내용(아이템 ID와 아이템 수량)을 설정할 수 있으며, 이 내용은 도달 작업의 프런트엔드 페이지에 표시되어 운영 작업을 설정하는 운영 담당자가 입력합니다필드: 파라미터의 이름으로, 발송 시 메시지 본문에서 사용합니다. 표시 이름: 작업을 생성할 때 표시되는 필드입니다. 입력 방식: 텍스트, 동적 텍스트, 숫자, 단일 선택 드롭다운, 날짜, 시간, 객체 그룹입니다. 기본값: 선택 사항이며, 입력 방식을 선택한 후 입력합니다. 힌트 문구: 작업을 생성할 때 입력란에 표시되는 힌트입니다(비필수). 필수: 체크하면 필수 항목이 되며, 기본적으로 체크되어 있지 않습니다
커스텀 파라미터채널 요구 사항에 따라 선택적으로 추가하며, 이 파라미터는 그대로 패스스루됩니다비필수. 필드: 파라미터의 이름으로, 발송 시 메시지 본문에서 사용합니다. 연관된 필드: 필드에 연결된 유저 속성으로, 메시지 본문을 보낼 때 필드 값에 이 속성 값을 사용합니다. 기본값: 선택 사항입니다. 기본값을 설정한 경우 속성 값이 비어 있으면 기본값을 사용하고, 기본값을 설정하지 않은 경우 속성 값이 비어 있으면 빈 값을 반환합니다

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

Webhook 채널로 푸시한 메시지는 필요에 따라 클라이언트/서버 측에서 클릭 이벤트를 수집할 수 있습니다. 수집 방법은 ThinkingAI 데이터 연동 매뉴얼의 이벤트 전송 방법을 참고하십시오. 이벤트 이름은 커스텀할 수 있으며, 이벤트 데이터에는 Webhook 채널에서 배포한 메시지의 #ops_receipt_properties 필드를 가져와 통째로 하나의 객체 속성으로 전송하면 됩니다. 다른 분석 시나리오가 있으면 이 이벤트에 다른 필드 속성을 추가할 수도 있습니다. 주의: 속성 필드 이름은 반드시 #ops_receipt_properties이고 타입은 객체여야 하며, 임의로 변경할 수 없습니다. 필드 이름을 변경하거나 필드 내부 내용을 수정하거나 필드를 텍스트 속성으로 잘못 전송하면 이후 데이터 사용에 문제가 발생합니다 코드 예시:

JSONObject properties = new JSONObject();
//Webhook 채널에서 배포한 message 메시지 본문에서 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);
이 문서가 도움이 되었나요?
이 페이지의 내용