> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# nora triggers

> Trigger 블록 관리. Flow의 API·웹훅·스케줄 진입

Trigger가 Flow를 시작하는 방식. 세 종류: `api`(SDK/CLI에서 호출), `webhook`(외부 HTTP POST), `schedule`(크론 기반).

## 명령

| 명령                                    | 설명                           |
| ------------------------------------- | ---------------------------- |
| `triggers create --kind <k>`          | Trigger 블록 추가.               |
| `triggers update <trigger-id>`        | 필드 패치(`--set-*` 플래그 다수).     |
| `triggers edit <trigger-id>`          | Trigger JSON을 `$EDITOR`에 열기. |
| `triggers delete <trigger-id>`        | Trigger 제거.                  |
| `triggers secret rotate <trigger-id>` | 새 웹훅/API 서명 시크릿 발급.          |

## `triggers create`

```bash theme={null}
nora triggers create --kind webhook --name "customer-events"
```

플래그:

* `--kind`(필수) `api` / `webhook` / `schedule`.
* `--name <n>` 표시 이름.
* `--config <json>` 종류별 인라인 설정.
* `--x <n>`, `--y <n>` 캔버스 위치.

명령이 생성한 Trigger의 ID를 출력(그리고 `webhook`/`api`에는 초기 시크릿도. 지금 복사할 것. 한 번만 표시).

## `triggers update`

```bash theme={null}
nora triggers update tr_events \
  --set-kind schedule \
  --set-schedule-mode preset \
  --set-period daily \
  --set-time 09:00 \
  --set-timezone Asia/Seoul
```

Update 플래그가 많음. 아래에 그룹별로.

### Update 플래그 (그룹별)

**정체성**

* `--set-name <n>`
* `--set-kind api|webhook|schedule`
* `--set-x <n>`, `--set-y <n>`, `--set-width <n>`

**Schedule 설정**(kind = `schedule`)

* `--set-schedule-mode preset|cron`
* `--set-cron <expr>` mode = `cron` 용, 예: `"0 9 * * *"`.
* `--set-period daily|weekly|monthly|yearly` mode = `preset` 용.
* `--set-time HH:MM` preset 용.
* `--set-day-of-week 1..7` weekly 용.
* `--set-day-of-month 1..31` monthly 용.
* `--set-month-of-year 1..12` yearly 용.
* `--set-interval <n>` 간격 수.
* `--set-timezone <IANA>` 예: `America/Los_Angeles`.
* `--set-schedule-input <text>` 스케줄 실행마다 넣는 페이로드.
* `--set-schedule-thread-id <id>` 채팅 Agent 용, 게시할 스레드.
* `--set-schedule-user-id <id>` 사용자 귀속.
* `--set-schedule-tts true|false` text-to-speech 입력으로 다룸.

**Webhook 설정**(kind = `webhook`)

* `--set-webhook-slug <s>` 경로 접미사(URL이 `.../trigger/webhook/<slug>`가 됨).
* `--set-webhook-input-path <json-path>` 본문에서 입력 추출.
* `--set-webhook-image-path <json-path>` 이미지 데이터 추출.
* `--set-webhook-audio-path <json-path>` 오디오 데이터 추출.
* `--set-webhook-auth-kind <k>` `none` / `secret` / `header`.
* `--set-webhook-auth-header <name>` `header` auth의 헤더 이름.

**API 설정**(kind = `api`)

* `--set-api-slug <s>` 경로 접미사.
* `--set-api-auth-kind <k>` `none` / `secret` / `header`.
* `--set-api-auth-header <name>`.

**한꺼번에**

* `--patch <json>` 임의 병합.

설정 패치는 기존 설정에 deep-merge 됨.

## `triggers edit`

```bash theme={null}
nora triggers edit tr_events
```

`$EDITOR`에 전체 JSON. 저장하면 적용.

## `triggers delete`

```bash theme={null}
nora triggers delete tr_events
```

## `triggers secret rotate`

```bash theme={null}
nora triggers secret rotate tr_events
```

새 서명 시크릿 발급. 평문을 한 번 출력하니 호출자에 복사. 이전 시크릿이 60분 동안 그대로 돼, 다운타임 없이 호출자를 업데이트 가능.

스케줄로 돌리거나(분기마다가 흔함) 새는 게 의심되면 바로 돌림.

## 레시피

### 매일 오전 9시 서울 시간 스케줄 추가

```bash theme={null}
TR=$(nora triggers create --kind schedule --name "daily-9am" | jq -r '.id')

nora triggers update $TR \
  --set-schedule-mode preset \
  --set-period daily \
  --set-time 09:00 \
  --set-timezone Asia/Seoul \
  --set-schedule-input "일일 롤업. 어제 티켓 요약"
```

Flow를 배포하면 스케줄이 걸리기 시작.

### CMS 용 웹훅 트리거 추가

```bash theme={null}
TR=$(nora triggers create --kind webhook --name "cms-hook" | jq -r '.id')

nora triggers update $TR \
  --set-webhook-slug cms \
  --set-webhook-input-path payload.body \
  --set-webhook-auth-kind secret

nora triggers secret rotate $TR  # 시크릿 캡처
```

웹훅 URL: `https://api.platform.nora.my/trigger/webhook/<flow-slug>/cms`. `X-Nora-Signature`로 POST 하도록 CMS를 설정.

### preset 스케줄을 cron으로 전환

```bash theme={null}
nora triggers update tr_daily \
  --set-schedule-mode cron \
  --set-cron "0 9 * * MON-FRI"    # 평일 오전 9시
```

Cron이 preset보다 표현력이 큼. daily/weekly/monthly 패턴을 넘는 건 다 cron으로.

### 웹훅이 추출하는 입력 경로 바꾸기

옛 CMS 모양: `{ "body": "..." }`, 경로 `body`.

새 모양: `{ "message": { "body": "..." } }`:

```bash theme={null}
nora triggers update tr_cms --set-webhook-input-path message.body
```

변경을 라이브로 하려면 Flow 배포.