Webhook 구성 연동 문서

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

1. 소개

구성 센터의 Webhook 채널은 외부 시스템 또는 내부의 다른 모듈과 상호 통신하기 위한 연결 메커니즘을 구축하는 것을 목적으로 합니다. 구성 센터는 Webhook을 통해 특정 데이터를 지정된 수신 측으로 보낼 수 있으며, 수신 측은 적절히 처리한 후 구성 센터 데이터와의 동기화, 특정 작업 실행, 데이터의 추가 배포 등의 기능을 구현할 수 있습니다.

2. Webhook 채널 서비스

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

Webhook 채널 Request

• 입력 파라미터 방식: 구성 센터에서 생성하며, POST 방식으로 요청을 보냅니다
• Content - Type: application/json으로 설정합니다
• 요청 본문 구조: 요청 본문 request_body는 JSONArray이며, 한 배치에 여러 메시지 데이터를 보낼 수 있습니다. 각 메시지 데이터는 특정 구성 항목 하나와 관련된 메시지를 나타냅니다
• 입력 요청 형식: 기본 요청 파라미터 형식은 다음과 같습니다

[{
    "opType": "${opTypeValue}",
    "configInfo": {
        "configId": "${configIdValue}",
        "templateId": "${templateIdValue}",
        "strategyId": "${strategyIdValue}"
    },
    "targetType": "${targetTypeValue}",
    "targetEnv": ${targetEnvValue},
    "targetAudience": ${targetAudienceValue},
    "configParams": ${configParamsValue},
    "#ops_receipt_properties": ${#ops_receipt_propertiesValue},
    "isEndPush": ${isEndPushValue}
}]

위 파라미터 이름은 커스텀할 수 있습니다. 조정이 필요하면 ThinkingAI 담당자에게 문의하십시오

파라미터 이름	파라미터 타입	파라미터 설명	비고
opType	문자열	${opTypeValue}는 플레이스홀더입니다(이하 동일). 기본 값은 online, suspend, offline이며, 각각 프런트엔드의 활성화(편집 후 다시 활성화), 효력 일시 중지, 비활성화 작업에 해당합니다.	전략이 만료로 비활성화되는 경우 기본적으로 비활성화 알림을 배포하지 않습니다. 활성화하려면 ThinkingAI 담당자에게 문의하십시오.
configId	문자열	구성 항목 ID는 연동된 비즈니스 모듈 하나를 식별하는 데 사용됩니다	구성 항목에 대한 설명은 구성 항목 관리를 참고하십시오
templateId	문자열	템플릿 ID는 구체적인 비즈니스 기능 형태를 식별하는 데 사용됩니다.	템플릿에 대한 설명은 구성 템플릿 관리를 참고하십시오
strategyId	문자열	전략 ID는 구성 전략의 고유 ID로, 전략의 전체 라이프사이클 관리에 사용됩니다.	전략에 대한 설명은 구성 전략 관리를 참고하십시오
targetType	문자열	targetType에 사용할 수 있는 값은 all/targetEnv/targetAudience이며, 각각 전체, 환경 단위 구성, 유저 단위 구성에 해당합니다.	대상 환경과 타겟 유저에 대한 소개는 구성 전략 관리의 타겟 오디언스 부분을 참고하십시오
systemId (선택 사항)	JSON	구성 센터를 통해 여러 다운스트림 시스템과 연동할 때 시스템 연동 식별자를 활성화할 수 있습니다. 활성화하면 유저 단위 구성의 활성화 요청은 시스템 연동 식별자 필드 값에 따라 분할하여 배포되며, 일시 중지 또는 비활성화 작업 시에도 요청에 전체 대상 시스템 값이 포함됩니다. 이를 통해 webhook 서비스에서 중계 처리를 하기 쉽습니다.	시스템 연동 식별자 설정은 구성 채널 설정을 참고하십시오
targetEnv	JSON	프런트엔드에서 설정한 대상 환경 조건으로, webhook server에서 파싱하여 처리해야 합니다. 환경 조건 형식 예시는 2.2의 전략 활성화 요청을 참고하십시오. 여러 조건은 AND 관계입니다.	효력 일시 중지 및 비활성화 요청을 배포할 때는 이 파라미터가 포함되지 않습니다
targetAudience	JSONArray	타겟 유저 목록입니다. 유저 정보를 받으려면 Webhook 채널에서 유저 속성을 커스텀 파라미터로 추가해야 합니다. 구성 채널 설정의 유저 파라미터 부분을 참고하십시오.	효력 일시 중지 및 비활성화 요청을 배포할 때는 이 파라미터가 포함되지 않습니다
configParams	JSON	구성 템플릿으로 설정한 구체적인 파라미터 내용입니다.	효력 일시 중지 및 비활성화 요청을 배포할 때는 이 파라미터가 포함되지 않습니다
#ops_receipt_properties	JSON	패스스루 파라미터로, 전략 자동 분석에 사용되며 현재는 처리할 필요가 없습니다.	AE 운영 모듈 시스템에서 기본으로 추가
isEndPush	불리언	이번 푸시의 종료 여부를 나타내는 식별자로, 유저 단위 구성 배포가 완료될 때만 배포됩니다.

주의: targetAudience와 configParams의 파라미터에서 모든 타입의 데이터(정수, 소수, 날짜 등)는 요청을 보낼 때 모두 문자열 타입으로 전송됩니다.

2.2 예시

전략 활성화 요청

환경 단위 구성 배포

"serverId"를 환경 조건으로 사용하는 경우를 예로 듭니다

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "targetType": "targetEnv",
    "syetemId": {   // 시스템 연동 식별자를 활성화한 경우에만 이 파라미터를 배포합니다
        "serverId":["101","102"]
    },
    "targetEnv": {
        "serverId":["101","102"]
    },
    "configParams": {
        "title": "demoTitle",
        "body": "demoBody"
    },
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "878c14fd1f266a16e8ba795085219ab0",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121001"
    }
}]

유저 단위 구성 배포

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121002"
    },
    "configParams": {
        "title": "demoTitle",
        "body": "demoBody"
    },
    "targetType": "targetAudience",
    "syetemId": { // 시스템 연동 식별자를 활성화한 경우에만 이 파라미터가 있으며, 시스템 연동 식별자 값에 따라 유저 패키지를 분할하여 배포합니다
        "serverId":["101"]
    },
    "targetAudience": [{
        "#user_id": "996080782348914698",
        "accountID": "jsxzdym",
        "serverID": "12"
    }, {
        "#user_id": "1308438872845193216",
        "accountID": "jsnjddk",
        "serverID": "16"
    }],
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "e0c24f7e5b05bfbccb72bdf56903d1e3",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121002"
    }
}]

시스템 연동 식별자를 활성화한 후 전략을 편집하여 새 버전을 게시하고 활성화하면, 활성화 요청 전에 해당 전략이 적용된 적이 있는 모든 시스템에 전략 변경 알림을 먼저 배포하여 다운스트림에서 기존 데이터를 처리할 수 있도록 합니다. 이 알림은 시스템 연동 식별자를 활성화한 경우에만 배포됩니다.

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121002"
    },
    "configParams": {
        "title": "demoTitle",
        "body": "demoBody"
    },
    "targetType": "targetAudience",
    "syetemId": {    // 전략이 적용된 적이 있는 시스템 값 목록
        "serverId":["101", "102", "103"]
    },
    "targetAudience": [],
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "e0c24f7e5b05bfbccb72bdf56903d1e3",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121002"
    }
}]

전략 활성화는 기본적으로 배치로 나누어 푸시되며, 아래는 푸시 완료 식별자입니다.

[{
    "opType": "online",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "isEndPush": true,
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "9ea9b1f599774987d03c0a838b9aa14d",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121001"
    }
}]

전략 효력 일시 중지 요청

[{
    "opType": "suspend",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "syetemId": {  // 시스템 연동 식별자를 활성화한 경우에만 이 파라미터가 있습니다
        "serverId":["101","102"]
    },
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "0b33c3fc4b5c0a25c5a7122788f6c952",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121001"
    }
}]

전략 비활성화 요청

[{
    "opType": "offline",
    "configInfo": {
        "configId": "demoConfig001",
        "templateId": "demoTemplate001",
        "strategyId": "2024121001"
    },
    "syetemId": {  // 시스템 연동 식별자를 활성화한 경우에만 이 파라미터가 있습니다
        "serverId":["101","102"]
    },
    "#ops_receipt_properties": {
        "ops_project_id": 1,
        "ops_request_id": "0b33c3fc4b5c0a25c5a7122788f6c952",
        "ops_config_id": "demoConfig001",
        "ops_template_id": "demoTemplate001",
        "ops_strategy_id": "2024121001"
    }
}]

2.3 Webhook 채널 Response

다음 파라미터 형식으로 요청에 응답하십시오.

{
    "return_code": 0,
    "return_message": "success",
    "data": {
        // fail_list의 각 요소는 실패한 객체 정보이며, 오류 메시지와 오류 객체의 번호를 포함합니다. 오류 객체 번호는 1부터 시작합니다. 예: 객체 정보 5개를 보내 번호가 1-5이고 3개 성공, 2개 실패이며 그중 2번째와 4번째가 실패한 경우 다음과 같이 반환합니다
        "fail_list": [{
            "index": 2,
            "message": "system error"
        }, {
            "index": 4,
            "message": "push id not found"
        }]
    }
}

파라미터 이름	파라미터 타입	필수 여부	파라미터 설명
return_code	Integer	예	반환 코드 0은 성공(또는 일부 성공)을 의미 1은 실패를 의미
return_message	String	아니요	반환 정보
data	Object	아니요	반환 데이터
data.fail_list	Array	아니요	return_code=0인 경우, data.fail_list가 [] 또는 null이면 전체 성공으로 간주합니다 data.fail_list가 비어 있지 않으면 일부 실패이며, 실패 상세 정보는 list에 정의된 내용입니다. 비즈니스상 일부 실패가 발생하지 않는 경우 []를 그대로 전달하면 됩니다. 주의: API 처리 로직에서 사전 검증을 수행하여 fail_list에 담아 AE로 반환하는 것을 권장합니다. 이렇게 하면 작업의 푸시 성공 지표 통계가 더 정확해집니다. 실패 목록에 있는 객체의 index 속성은 번호를 나타내며, 번호는 0이 아닌 1부터 시작합니다! message 필드는 필수는 아니지만, 오류 발생 시 문제를 쉽게 해결할 수 있도록 반환할 것을 강력히 권장합니다 return_code=1인 경우 data.fail_list에 무엇을 전달하든 전체 실패로 간주합니다.

2.4 요청 인증

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

인증 기능은 기본적으로 비활성화되어 있습니다. Webhook 채널 server에 인증이 필요하지 않으면 이 부분을 건너뛰어도 됩니다.

인증을 지원하려면 채널을 설정할 때 채널 검증 스위치를 켜야 합니다. 그러면 발송 측에서 서명을 http 요청 헤더에 추가하며, Key는 X-AE-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.5 요청 동시성 성능

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

3. Webhook 채널 설정 가능 파라미터 소개

다음 파라미터는 기본적으로 백엔드에서 설정합니다. 수정이 필요하면 ThinkingAI 담당자에게 문의하십시오

구성 항목	선택 가능한 값	기본값	설정 설명
구성 센터 전용 host 노드	구체적인 host	없음	기본적으로 격리하지 않습니다. 격리가 필요하면 여러 노드를 쉼표로 구분하여 설정합니다. 예: ta4,ta5
구성 센터 webhook 요청 형식	구체적인 json	없음	기본 형식 템플릿은 위의 예시를 참고하십시오. 기존 API에 연동할 계획이고 푸시에 성공한 유저를 구분할 필요가 없는 경우, 요청 형식 템플릿을 커스텀하면 별도 개발 없이 기존 서비스에 바로 연동할 수 있습니다.
"1회 게시 종료" 상태 알림 발송	활성화, 비활성화	활성화	타겟 유저 유형의 활성화 푸시에 포함된 유저 수가 많으면 분할하여 Webhook 서버 측으로 푸시합니다. 서버 측에서 이번 푸시의 완료 여부를 판단해야 할 때 이 요청으로 판단할 수 있습니다.
자동 비활성화 시 요청 배포 여부	활성화, 비활성화	비활성화	전략이 설정된 시간에 자동으로 비활성화될 때는 기본적으로 Webhook 서버 측으로 비활성화 요청을 보내지 않습니다. 활성화하면 자동 비활성화 시에도 비활성화 요청을 보내며, 형식은 수동 비활성화와 같습니다.
구성 항목 배포 명령 타입	3가지, 5가지	3가지	기본값은 online, offline, suspend 세 가지이며, 편집 후 활성화(re_online)와 강제 비활성화(force_offline)를 구분하도록 설정할 수 있습니다.
발송 속도 제한	-1，[1,10000]	속도 제한 없음	단위: 회/초. -1로 설정하면 속도를 제한하지 않습니다. 1-10000 사이의 숫자(예: 500)로 설정하면 다운스트림 Webhook 채널 서버로 초당 최대 500회의 요청을 보낸다는 의미입니다.
발송 배치 크기	[1,5000]	1000	1회 호출 파라미터의 JsonArray에 포함되는 요소 수를 나타냅니다 배치 크기를 크게 설정하면 메시지 발송 효율을 높일 수 있습니다 배치 크기를 작게 설정하면 발송 속도는 느려지지만 안정성은 더 높아집니다 1000으로 설정하는 것을 권장하며, 최대 5000까지 설정할 수 있습니다
타임아웃 시간	[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 운영 모듈은 이번 호출을 실패로 간주합니다