외부 연동

연동이란?

**연동(Integration)**은 LexQ를 외부 서비스에 연결합니다. 규칙의 액션이 실행될 때, LexQ가 쿠폰 시스템, 포인트 플랫폼, 알림 서비스, 또는 웹훅 엔드포인트를 호출할 수 있습니다. 연동은 한 번 설정한 후 규칙 액션에서 ID로 참조합니다.

연동 유형

유형	설명	사용 사례
`WEBHOOK`	HTTP 엔드포인트 호출	주문 처리, 커스텀 로직
`COUPON`	외부 서비스를 통해 쿠폰 발행	웰컴 쿠폰, 시즌 프로모션
`POINT`	포인트 적립 또는 차감	로열티 프로그램, 캐시백
`NOTIFICATION`	SMS, 이메일, 푸시 발송	주문 확인, 알림
`CRM`	사용자 데이터 또는 태그 동기화	고객 세분화
`MESSENGER`	채팅 플랫폼으로 메시지 발송	고객 지원 자동화

연동 유형은 외부 서비스의 카테고리입니다 — 액션 타입과는 독립적입니다. 액션이 어떤 연동 유형으로 라우팅되는지는 dispatcher가 결정하며, 액션 이름이 결정하지 않습니다.

연동 생성

콘솔

관리 → 연동 → 연동 생성으로 이동, 유형 선택 후 설정을 입력합니다.

CLI

lexq integrations save --json '{
  "type": "WEBHOOK",
  "name": "주문 처리 웹훅",
  "baseUrl": "https://api.example.com/webhooks/orders",
  "isActive": true
}'

필수 설정 확인

각 유형마다 필요한 설정 필드가 다릅니다:

lexq integrations config-spec --type WEBHOOK
lexq integrations config-spec --type COUPON

규칙에서 연동 사용

LexQ 엔진의 액션은 도메인 중립 원시(primitive) 입니다 — 전체 레퍼런스는 액션 타입을 참조하세요. 아래는 각 연동 유형이 호출되는 패턴입니다.

쿠폰 발행 — `EMIT_EVENT` + `COUPON` 연동

{
  "type": "EMIT_EVENT",
  "parameters": {
    "integrationId": "<쿠폰-연동-id>",
    "eventPayload": {
      "couponId": "WELCOME_10"
    }
  }
}

dispatcher는 EMIT_EVENT를 해당 연동 유형에 등록된 서비스로 라우팅합니다. eventPayload의 해석은 integration provider 책임입니다 — 엔진은 키를 검증하거나 변환하지 않습니다.

알림 — `EMIT_NOTIFICATION` + `NOTIFICATION` 연동

{
  "type": "EMIT_NOTIFICATION",
  "parameters": {
    "integrationId": "<알림-연동-id>",
    "targetVar": "phone_number",
    "notificationPayload": {
      "channel": "SMS",
      "templateId": "ORDER_CONFIRM"
    }
  }
}

targetVar는 수신자 팩트를 지정합니다 (phone_number, email, device_token 등). notificationPayload는 변경 없이 integration provider에 전달됩니다.

웹훅 — `EMIT_WEBHOOK` + `WEBHOOK` 연동

{
  "type": "EMIT_WEBHOOK",
  "parameters": {
    "url": "<웹훅-연동-id>",
    "method": "POST",
    "payloadTemplate": {
      "text": "규칙 {{ruleName}} 매칭 — {{fact.customer_tier}} 고객, 금액: {{output.payment_amount}}원"
    }
  }
}

payloadTemplate 필드는 선택 사항입니다. 생략하면 모든 팩트가 요청 본문으로 전송됩니다. 설정하면 템플릿 구조만 전송되며 {{변수}}가 실제 값으로 치환됩니다. 전체 변수 레퍼런스는 정책 규칙 — EMIT_WEBHOOK을 참조하세요.

포인트 적립 — `INCREMENT_FACT`

로열티 포인트 적립은 INCREMENT_FACT로 엔진 내부 팩트를 변경합니다:

{
  "type": "INCREMENT_FACT",
  "parameters": {
    "targetVar": "total_point",
    "refVar": "payment_amount",
    "method": "PERCENTAGE",
    "rate": 1
  }
}

generatedVariables.total_point__delta는 적용된 증분량을 노출합니다 (예: payment_amount: 100000에 1% 비율이면 1000).

엔진 액션 중 EMIT_WEBHOOK만이 엔진 내부에서 변수 치환을 수행합니다 (payloadTemplate을 통해). EMIT_EVENT와 EMIT_NOTIFICATION의 경우, 페이로드 값은 변경 없이 integration provider에 전달됩니다 — 치환과 해석은 provider 책임입니다.

연동 관리

lexq integrations list
lexq integrations get --id <integrationId>
lexq integrations save --json '{...}'
lexq integrations delete --id <integrationId>

장애 처리

실행 중 연동 호출이 실패하면 (네트워크 타임아웃, 5xx 응답 등) 장애 로그에 기록됩니다. 재시도, 건너뛰기, 해결 처리가 가능합니다:

lexq logs list --status PENDING
lexq logs action --id <logId> --action RETRY

변경 영향 시뮬레이션에서는 연동 호출이 항상 모킹됩니다. 드라이런에서는 콘솔의 외부 호출 모킹 토글로 제어합니다 (API 파라미터: mockExternalCalls, 기본값: true). false로 설정하면 실제 외부 호출을 시도하며, 실패 시 장애 로그에 기록됩니다.

연동이란?

연동 유형

연동 생성

콘솔

CLI

필수 설정 확인

규칙에서 연동 사용

쿠폰 발행 — `EMIT_EVENT` + `COUPON` 연동

알림 — `EMIT_NOTIFICATION` + `NOTIFICATION` 연동

웹훅 — `EMIT_WEBHOOK` + `WEBHOOK` 연동

포인트 적립 — `INCREMENT_FACT`

연동 관리

장애 처리

다음 단계

정책 규칙

문제 해결

​연동이란?

​연동 유형

​연동 생성

​콘솔

​CLI

​필수 설정 확인

​규칙에서 연동 사용

​쿠폰 발행 — EMIT_EVENT + COUPON 연동

​알림 — EMIT_NOTIFICATION + NOTIFICATION 연동

​웹훅 — EMIT_WEBHOOK + WEBHOOK 연동

​포인트 적립 — INCREMENT_FACT

​연동 관리

​장애 처리

​다음 단계

정책 규칙

문제 해결

연동이란?

연동 유형

연동 생성

콘솔

CLI

필수 설정 확인

규칙에서 연동 사용

쿠폰 발행 — `EMIT_EVENT` + `COUPON` 연동

알림 — `EMIT_NOTIFICATION` + `NOTIFICATION` 연동

웹훅 — `EMIT_WEBHOOK` + `WEBHOOK` 연동

포인트 적립 — `INCREMENT_FACT`

연동 관리

장애 처리

다음 단계