08. 변수와 시크릿¶

API 키를 워크플로우에 직접 적지 않기 위한 기능입니다. 사이드바 변수 화면에서 관리합니다.

두 종류가 있습니다¶

	시크릿 (Secrets)	변수 (일반 변수)
저장 방식	암호화	평문
화면 표시	값이 가려짐 (다시 못 봄)	값이 그대로 보임
참조	`${secrets.키}`	`${vars.키}`
넣을 것	API 키, 토큰, 비밀번호	도메인, 채널 ID, 임계값

서로 넘나들 수 없습니다. ${vars.*}로 시크릿을 꺼낼 수 없고, 반대도 안 됩니다. 실수로 민감한 값이 평문 경로로 새는 걸 막기 위한 구조입니다.

만들기¶

사이드바 변수로 들어갑니다.
시크릿 탭 또는 변수 탭을 고릅니다.
생성 버튼을 누르고 채웁니다.

항목	설명
Key	참조할 이름. 예: `OPENAI_API_KEY`
Value	실제 값
Description	무엇에 쓰는 값인지 메모 (선택)

만든 뒤에는 목록에서 복사 버튼을 누르면 ${secrets.OPENAI_API_KEY} 형태로 바로 복사됩니다. YAML에 붙여넣기만 하면 됩니다.

키 이름 규칙: 영문 대문자와 밑줄을 권합니다 (OPENAI_API_KEY, SLACK_CHANNEL_ID). 표현식에서 그대로 쓰이므로 공백이나 특수문자는 피하세요.

쓰기¶

- id: ai
  type: CALL
  integration: llm_chat
  input:
    apiContract: OPENAI_CHAT
    model: gpt-4o-mini
    apiKey: "${secrets.OPENAI_API_KEY}"       # ← 시크릿
    userPrompt: "..."

- id: fetch
  type: CALL
  integration: http_request
  input:
    uri: "${vars.API_BASE_URL}/orders"        # ← 일반 변수, 문장 안에 섞어 쓸 수 있음
    method: GET
    authenticate:
      authMethod: HEADERS
      data:
        Authorization: "Bearer ${secrets.MY_API_TOKEN}"

시크릿 값 바꾸기¶

시크릿은 저장하고 나면 다시 볼 수 없습니다. 값을 바꾸려면 새 값을 입력해 덮어씁니다. 편집창에서 값을 비워두고 저장하면 기존 값이 유지되고 설명만 바뀝니다.

이렇게 쓰면 좋습니다¶

✅ 이렇게¶

apiKey: "${secrets.OPENAI_API_KEY}"
uri: "${vars.SHOP_API_BASE}/v1/orders"
channel: "${vars.ALERT_CHANNEL_ID}"

❌ 이러지 마세요¶

apiKey: "sk-proj-abc123..."                    # YAML에 키를 그대로
uri: "https://api.myshop.com/v1/orders"        # 도메인이 바뀌면 워크플로우를 전부 수정

YAML에 키를 적으면 워크플로우를 복사하거나 공유할 때 키도 함께 새어나갑니다. 워크플로우 정의는 화면에서 그대로 보이고 복사할 수 있는 텍스트입니다.

자주 쓰는 변수 예¶

키	종류	예시 값
`OPENAI_API_KEY`	시크릿	`sk-proj-...`
`ANTHROPIC_API_KEY`	시크릿	`sk-ant-...`
`SHOP_API_TOKEN`	시크릿	쇼핑몰 API 토큰
`WEBHOOK_SECRET`	시크릿	웹훅 서명 검증 키 (아래)
`API_BASE_URL`	변수	`https://api.myshop.com`
`ALERT_CHANNEL_ID`	변수	`C0123ABCDEF`
`VIP_THRESHOLD`	변수	`100000`

이름이 정해져 있는 시크릿 — `WEBHOOK_SECRET`¶

대부분의 변수는 이름을 마음대로 지어도 되지만, WEBHOOK_SECRET 하나는 이음새가 이름으로 알아봅니다.

이 이름으로 시크릿을 등록하면, 그 워크스페이스의 모든 웹훅 트리거가 서명 검증을 요구하게 됩니다. 서명이 없거나 틀린 요청은 실행되지 않습니다.


등록 위치	변수 → 시크릿 탭
키	`WEBHOOK_SECRET` (정확히 이 이름)
값	아무 긴 임의 문자열 (예: `openssl rand -hex 32` 결과)
적용 범위	워크스페이스 전체의 웹훅 워크플로우

⚠️ 일반 변수로 등록하면 검증이 켜지지 않습니다. 반드시 시크릿 탭에서 만드세요.

⚠️ 켜는 순간 기존 웹훅 호출이 전부 막힙니다. 이미 돌고 있는 웹훅이 있다면 호출하는 쪽에 서명 헤더를 먼저 붙여둔 뒤 등록하세요.

만드는 법과 헤더 형식 → 03. 트리거 설정하기

주의할 점¶

워크스페이스마다 따로입니다. 워크스페이스가 여러 개면 각각 등록해야 합니다.
이름을 바꾸면 그 이름을 참조하던 워크플로우가 전부 실행 중 에러를 냅니다. 바꾸기 전에 어디서 쓰는지 확인하세요.
삭제하면 참조하던 워크플로우는 다음 실행부터 ExpressionResolveException으로 실패합니다.

다음 → 09. 데이터셋