# Webhook 트리거

> 다른 앱, 폼, 내 코드에서 HTTP POST 요청으로 워크플로를 시작하고, 프롬프트나 이미지 URL 같은 값을 실행에 전달하세요.

Source: https://nodaro.ai/ko/docs/nodes/automate/webhook-trigger

**Webhook 트리거** 노드는 다른 시스템이 워크플로의 고유한 Webhook 주소로 HTTP POST 요청을 보내면 워크플로를 시작합니다. 콘텐츠 관리 시스템, 폼, 자동화 도구 또는 내 코드에서 워크플로를 실행할 때 사용하세요. 요청은 프롬프트나 이미지 URL 같은 값을 실행에 전달할 수 있습니다. 트리거 자체는 무료입니다.

- Found in: Automate › Triggers
- Output: data
- API type: `webhook-trigger`

## 사용 시기
- 콘텐츠 관리 시스템에 새 글이 게시되면 동영상을 생성합니다.
- 제품 사진처럼 다른 앱이 보내는 이미지를 처리합니다.
- HTTP POST 요청을 보낼 수 있는 자동화 도구나 스크립트라면 어디에서든 워크플로를 시작합니다.
- 내 코드가 제어하는 콘텐츠 워크플로를 만듭니다.

## 빠른 시작
### 노드 추가
캔버스에서 Tab을 누르고 **자동화 › 트리거 › Webhook 트리거**를 선택하세요.

### 받을 값 정의
설정 패널의 **출력 파라미터**에서 값마다 **추가**를 클릭하세요. 각 파라미터에 JSON 본문의 키와 같은 이름과 유형을 지정하세요. 유형은 **텍스트**, **이미지 URL**, **동영상 URL**, **오디오 URL** 중 하나입니다. 각 파라미터는 노드의 출력이 됩니다.

### 브랜치 구성
출력을 그 값을 사용하는 노드에 연결하고, 그 뒤로 워크플로의 나머지 부분을 만드세요.

### 워크플로 저장
저장하면 Webhook 주소가 만들어집니다. 노드를 선택하면 설정 패널의 **Webhook URL** 아래에 전체 주소가 표시됩니다. 옆에 있는 복사 버튼을 클릭하세요.

### 요청 보내기
주소로 JSON 본문을 POST하세요. 워크플로가 본문의 값으로 실행됩니다.

Workflow: 콘텐츠 시스템이 프롬프트와 이미지 URL을 보내면 동영상 생성이 그 값으로 클립을 만들고, Webhook 출력이 완성된 동영상을 다시 보냅니다.

- Webhook 트리거 → 동영상 생성
- 동영상 생성 → Webhook 출력

## 출력 파라미터
| 필드 | 설명 |
| --- | --- |
| **이름** | JSON 본문에서 읽을 키입니다. 이름이 `prompt`이면 `"prompt"`의 값을 읽습니다. |
| **유형** | 값의 종류로, **텍스트**, **이미지 URL**, **동영상 URL**, **오디오 URL** 중 하나입니다. 유형에 따라 Nodaro가 트리거 다음의 노드들에 값을 전달하는 방식이 정해집니다. |

각 파라미터는 파라미터 이름이 붙은 노드 출력이 되며, 그 키의 값을 텍스트로 전달합니다. 본문에 없는 키는 그 출력을 비워 둡니다.

파라미터가 없으면 노드의 출력은 **페이로드** 하나뿐입니다. 본문에 `prompt`, `imageUrl`, `videoUrl`, `audioUrl` 키 중 하나라도 있으면 이 출력은 그 값들을 전달합니다. 그렇지 않으면 본문 전체를 JSON 텍스트로 전달합니다.

## 요청 보내기
Webhook 주소로 JSON 본문을 POST하세요. 본문의 키는 내 파라미터의 이름입니다.

```bash
curl -X POST "https://app.nodaro.ai/v1/webhooks/<token>" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A lighthouse at dawn, slow push-in", "imageUrl": "https://example.com/lighthouse.jpg"}'
```

셀프 호스팅 설치에서는 `https://app.nodaro.ai` 대신 내 설치의 주소를 사용하세요.

응답을 보면 무슨 일이 일어났는지 알 수 있습니다.

| 상태 | 의미 |
| --- | --- |
| `202` | 실행이 시작되었습니다. 본문에 그 실행의 `executionId`가 들어 있습니다. |
| `404` | 이 주소에 응답하는 Webhook이 없습니다. 예를 들어 노드가 삭제된 경우입니다. |
| `403` | API를 통해 트리거가 일시 중지되었습니다. |
| `409` | 워크플로가 이미 실행 중입니다. 본문에 그 실행의 `executionId`가 들어 있습니다. |
| `429` | 이 토큰으로 1분 안에 10개가 넘는 요청이 도착했습니다. |

## 주소와 토큰
- **저장하면 주소가 만들어집니다.** 노드를 추가하고 워크플로를 저장하면 Nodaro가 64자의 임의 토큰과 `POST /v1/webhooks/<token>` 주소를 만듭니다. 처음 저장하기 전에는 설정 패널에 “워크플로를 저장하면 이 트리거의 URL이 만들어집니다”라고 표시됩니다.
- **설정 패널에서 복사하세요.** 저장한 뒤에는 패널의 **Webhook URL** 아래에 전체 주소가 복사 버튼과 함께 표시됩니다. 그 아래에는 토큰이 줄여서 표시되며, 토큰에도 별도의 **복사** 버튼이 있습니다.
- **노드에는 줄인 주소가 표시됩니다.** 캔버스의 노드에는 `…/v1/webhooks/a1b2c3d4••••`처럼 토큰의 앞부분만 있는 주소가 표시됩니다. 그래서 캔버스 스크린샷에 토큰이 드러나지 않습니다.
- **소유자만 볼 수 있습니다.** 주소는 워크플로 소유자의 것입니다. 워크플로를 편집할 수 있는 다른 사람에게는 주소 대신 저장 안내 메시지가 표시됩니다.
- **주소는 바뀌지 않습니다.** 토큰은 한 번 만들어진 뒤 이후의 모든 저장에서 유지되므로, 다른 시스템에 알려 준 주소는 계속 작동합니다.
- **노드를 삭제하면 주소가 폐기됩니다.** Webhook 트리거를 삭제하고 저장하면 주소가 더 이상 작동하지 않습니다.
- **API에서 주소를 읽으세요.** `GET /v1/workflows/<id>/triggers`는 각 트리거의 주소를 `/v1/webhooks/<token>` 경로로, 토큰과 함께 반환합니다. `config.nodeId`가 노드의 ID인 트리거가 이 노드의 트리거입니다.

주소는 공개되어 있으며, 토큰이 유일한 보호 수단입니다. 주소를 아는 사람은 누구나 워크플로를 시작할 수 있고, 모든 실행은 워크플로 소유자에게 청구됩니다. 주소를 비밀로 유지하세요.

## 제한
- 토큰마다 **1분에 요청 10개**. 그보다 많은 요청은 상태 `429`를 받습니다.
- **한 번에 실행 하나.** 워크플로가 실행 중인 동안 새 요청은 상태 `409`를 받습니다.

## Webhook 실행의 범위
노드에 연결된 트리거는 자기 브랜치만 실행합니다. 트리거 다음의 노드들과, 그 노드들이 입력으로 필요로 하는 모든 노드입니다. 아무것에도 연결되지 않은 트리거는 워크플로 전체를 실행합니다. 따라서 한 워크플로에 Webhook 트리거와 [일정 트리거](https://nodaro.ai/docs/nodes/automate/schedule-trigger)처럼 여러 트리거를 두고, 각 트리거가 자기 브랜치를 시작하게 할 수 있습니다.

노드는 직접 그린 연결로 이어져 있거나, 트리거가 입력을 보내는 [그룹](https://nodaro.ai/docs/nodes/automate/group) 안에 있거나, 필드 매핑으로 이어져 있으면 연결된 것으로 봅니다. 편집기에서의 수동 실행, API에서 시작한 실행, 게시된 앱의 실행은 트리거의 브랜치로 제한되지 않습니다.

## 크레딧
Webhook 트리거는 무료입니다. 각 실행은 실행하는 노드의 비용을 내며, 이 비용은 워크플로 소유자에게 청구됩니다.

## 팁
- **이름을 맞추세요.** 다른 시스템이 보내는 키 이름을 대소문자까지 정확하게 사용하세요.
- **요청 하나로 테스트하세요.** 운영 중인 시스템을 연결하기 전에 `curl`로 요청을 하나 보내 보세요.
- **결과를 다시 보내세요.** 워크플로 끝에 [Webhook 출력](https://nodaro.ai/docs/nodes/publish/webhook-output)을 두어 결과를 내 서버로 보내세요.
- **일정에 따라서도 실행하세요.** 같은 워크플로를 타이머로 실행하려면 [일정 트리거](https://nodaro.ai/docs/nodes/automate/schedule-trigger)를 추가하세요.

전체 API는 [Webhook](https://nodaro.ai/docs/developers/api/webhooks)을 읽어 보세요.

## 자주 묻는 질문

### 다른 앱에서 Nodaro 워크플로를 시작하려면 어떻게 하나요?

워크플로에 Webhook 트리거를 추가하고 저장하세요. 저장하면 Webhook 주소가 만들어집니다. 다른 앱이 JSON 본문과 함께 그 주소로 HTTP POST 요청을 보내면 워크플로가 실행됩니다.

### Webhook URL은 어디에서 찾나요?

워크플로를 저장한 다음 Webhook 트리거 노드를 선택하세요. 설정 패널의 Webhook URL 아래에 전체 주소가 복사 버튼과 함께 표시됩니다. 주소는 /v1/webhooks/ 뒤에 토큰이 붙은 형태이며, 이후에 다시 저장해도 바뀌지 않습니다. 코드에서는 GET /v1/workflows/<id>/triggers로 읽을 수 있습니다.

### 워크플로에 프롬프트나 이미지를 전달하려면 어떻게 하나요?

설정 패널에서 값마다 출력 파라미터를 추가하고, JSON 본문의 키와 같은 이름과 텍스트나 이미지 URL 같은 유형을 지정하세요. 각 파라미터는 그 키의 값을 전달하는 노드 출력이 됩니다.

### Webhook 주소는 안전한가요?

주소에 들어 있는 토큰이 유일한 보호 수단입니다. 주소를 아는 사람은 누구나 워크플로를 시작할 수 있고, 모든 실행은 워크플로 소유자에게 청구됩니다. 주소를 비밀로 유지하고, 주소를 폐기하려면 노드를 삭제하고 저장하세요.

### Webhook은 요청을 얼마나 받을 수 있나요?

토큰마다 1분에 최대 10개의 요청을 받습니다. 워크플로가 이미 실행 중일 때 도착한 요청은 상태 코드 409로 거부됩니다.