03. 트리거 설정하기¶

워크플로우를 무엇이 깨우는지 정하는 문서입니다. 방법은 두 가지입니다.

방식	언제 도나요	예시
웹훅 (`WEBHOOK`)	누가 주소를 호출할 때마다	주문이 들어오면, 폼이 제출되면
스케줄 (`SCHEDULER`)	정해둔 시각마다	매일 아침 9시, 매주 월요일

둘 다 ENTRYPOINT 노드에 적습니다. ENTRYPOINT는 워크플로우당 정확히 하나입니다.

웹훅 트리거¶

가장 단순한 형태¶

- id: trigger
  name: 웹훅 트리거
  type: ENTRYPOINT

trigger를 아예 생략하면 웹훅이 기본값입니다. 이 경우 받은 요청 본문이 통째로 그대로 다음 노드에 전달됩니다.

받을 데이터를 검사하고 싶다면¶

input-schema를 붙이면 이음새가 요청을 검사해줍니다.

- id: trigger
  name: 주문 웹훅
  type: ENTRYPOINT
  trigger:
    kind: WEBHOOK
    input-schema:
      type: object
      required: [orderId, customerName]
      properties:
        orderId:      { type: string }
        customerName: { type: string }
        amount:       { type: number }

input-schema를 쓰면 동작이 이렇게 바뀝니다.

상황	결과
`required` 필드가 요청에 없음	실행 실패
`properties`에 없는 필드가 요청에 있음	조용히 버려짐 (다음 노드로 안 넘어감)
`properties`에 있는 필드	정상적으로 넘어감

즉 input-schema는 화이트리스트입니다. 뒤에서 쓰려는 필드는 전부 properties에 적어야 합니다. 적었는데 값이 안 넘어온다면 properties에서 빠뜨린 게 아닌지 먼저 확인하세요.

호출 주소¶

워크플로우 상세의 Overview 탭에서 확인·복사할 수 있습니다. 형식은 이렇습니다.

POST https://api.eeumsae.com/webhooks/{워크스페이스ID}/{워크플로우slug}

{워크플로우slug}는 워크플로우를 만들 때 정한 slug입니다.

curl -X POST "https://api.eeumsae.com/webhooks/<워크스페이스ID>/order-notify" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "ORD-1234", "customerName": "김보찬", "amount": 25000}'

호출하면 바로 응답이 돌아오고, 워크플로우는 뒤에서 비동기로 실행됩니다. 응답이 200이라고 워크플로우가 성공했다는 뜻은 아닙니다 — "잘 접수했다"는 뜻입니다. 결과는 실행 이력에서 확인하세요. → 10. 실행과 모니터링

받은 값 꺼내 쓰기¶

${nodes.trigger.response.body.orderId}

trigger는 ENTRYPOINT 노드의 id입니다. 노드 id를 my-trigger로 지었다면 ${nodes.my-trigger.response.body.orderId}가 됩니다.

스케줄 트리거¶

정해둔 시각마다 자동으로 돕니다.

- id: trigger
  name: 매일 아침 트리거
  type: ENTRYPOINT
  trigger:
    kind: SCHEDULER
    cron: "0 0 9 * * ?"
    timezone: "Asia/Seoul"
    lookback: PT24H

항목	필수	설명
`cron`	필수	6자리 cron 표현식 (아래 참고)
`timezone`	선택	기본값 `UTC`. 한국 시간이면 반드시 `Asia/Seoul`을 적으세요
`lookback`	선택	조회 기간을 자동 계산해 넘겨줍니다 (아래 참고)

cron 표현식은 6자리입니다¶

흔히 보는 5자리 cron과 다릅니다. 맨 앞에 초(second)가 붙습니다.

┌───────────── 초 (0-59)
│ ┌─────────── 분 (0-59)
│ │ ┌───────── 시 (0-23)
│ │ │ ┌─────── 일 (1-31)
│ │ │ │ ┌───── 월 (1-12)
│ │ │ │ │ ┌─── 요일 (0-7, 0과 7은 일요일)
│ │ │ │ │ │
0 0 9 * * ?

자주 쓰는 것들입니다.

하고 싶은 것	cron
매일 오전 9시	`0 0 9 * * ?`
매일 오전 9시 30분	`0 30 9 * * ?`
매시간 정각	`0 0 * * * ?`
30분마다	`0 0/30 * * * ?`
평일(월~금) 오전 8시	`0 0 8 ? * MON-FRI`
매주 월요일 오전 10시	`0 0 10 ? * MON`
매월 1일 자정	`0 0 0 1 * ?`

* 와 ?: 일(day) 자리와 요일(day-of-week) 자리는 서로 충돌하므로 한쪽에는 ? 를 씁니다. 날짜로 지정하면 요일 자리에 ?, 요일로 지정하면 날짜 자리에 ?를 넣으면 됩니다.

시간대 주의: timezone을 안 적으면 UTC입니다. 0 0 9 * * ?만 적으면 한국 시간으로 오후 6시에 돕니다. 한국 시간 기준으로 돌리려면 timezone: "Asia/Seoul"을 꼭 넣으세요.

lookback — "지난 24시간 것만 가져와"¶

매일 도는 리포트를 만들 때, 늘 "지난 하루치"를 조회하게 됩니다. 그 기간의 시작·끝 시각을 이음새가 계산해서 넘겨주는 기능입니다.

trigger:
  kind: SCHEDULER
  cron: "0 0 9 * * ?"
  timezone: "Asia/Seoul"
  lookback: PT24H        # 24시간

이렇게 하면 트리거 출력에 두 값이 생깁니다.

값	뜻
`${nodes.trigger.response.body.windowStart}`	실행 시각 − lookback
`${nodes.trigger.response.body.windowEnd}`	실행 시각

둘 다 ISO-8601 문자열입니다 (예: 2026-05-19T09:00:00.000+09:00).

- id: fetch-orders
  name: 주문 조회
  type: CALL
  integration: http_request
  input:
    uri: "https://api.example.com/orders"
    method: GET
    queryParams:
      from: "${nodes.trigger.response.body.windowStart}"
      to: "${nodes.trigger.response.body.windowEnd}"

lookback 값은 ISO-8601 기간 형식으로 씁니다.

쓰고 싶은 기간	표기
1시간	`PT1H`
6시간	`PT6H`
24시간	`PT24H`
7일	`P7D`
30분	`PT30M`

lookback을 안 적으면 windowStart / windowEnd가 아예 생기지 않습니다. 참조하면 실행 중 에러가 납니다.

두 방식 비교¶

	웹훅	스케줄
시작 조건	외부에서 호출할 때	정해진 시각마다
입력 데이터	요청 본문 (원하는 대로)	없음 (`lookback` 쓰면 기간 값)
테스트	`curl`로 바로 가능	시각을 기다리거나 MCP로 즉시 실행
어울리는 일	이벤트 반응 (주문·가입·문의)	정기 리포트·정기 점검·정기 동기화

다음 → 04. 통합 카탈로그