웹훅과 폼
트리거 게이트웨이 (works-open)
외부에서 워크플로우를 호출하는 모든 트리거 경로(웹훅/폼/텔레그램)는 트리거 게이트웨이 https://works-open.ssemworks.io 를 거칩니다.
- 게이트웨이는 허용 경로만 통과시킵니다:
/api/webhook*,/api/form*. 관리 API(/rest,/api/saga등)는 외부에서 차단됩니다(404). - 에디터의 Webhook URLs 섹션에 표시되는 Production URL 이 이 게이트웨이 주소입니다.
웹훅 호출
워크플로우를 활성화한 뒤 Production URL 로 호출합니다.
curl -X POST "https://works-open.ssemworks.io/api/webhook/<웹훅경로>" \
-H "Content-Type: application/json" \
-d '{"name": "ssem", "n": 42}'
Content-Type 을 반드시 지정하세요
본문을 보내는 호출은 Content-Type: application/json 헤더가 필요합니다. 헤더 없는 curl -d 는 폼 데이터로 해석을 시도하다 라우트에 도달하기 전에 거부될 수 있습니다.
- Test URL(
/api/webhook-test/…)은 저작 중 테스트용입니다. - 웹훅 노드의 HTTP 메서드/경로/응답 설정은 웹훅 노드 레퍼런스를 참고하세요.
인증
웹훅 노드에 인증을 설정할 수 있습니다.
| 방식 | 동작 |
|---|---|
| 없음(none) | 누구나 호출 가능 |
| Header Auth | 지정 헤더 이름/값 일치 필요 — 불일치 시 403 |
| Basic Auth | RFC7617 Basic — 자격 불일치/형식 오류 시 401/403 |
| JWT | 서명 검증 |
인증 실패 응답에는 자격증명 상세가 노출되지 않습니다.
응답 모드 (responseMode)
| 모드 | 응답 시점 | 응답 본문 |
|---|---|---|
onReceived | 요청 수신 즉시 | 고정 확인 응답 |
responseNode | 웹훅 응답 노드 실행 시 | respondToWebhook 노드가 지정한 본문/상태 |
lastNode | 워크플로우 완료 시 | 최종 노드의 출력 |
responseNode/lastNode 는 워크플로우가 끝날 때까지 HTTP 연결을 유지(동기 홀드)했다가 응답합니다.
폼 (Form)
폼 트리거는 URL 로 접속하면 웹 폼을 렌더링하고, 제출되면 워크플로우가 시작됩니다.
GET https://works-open.ssemworks.io/api/form/<폼경로> ← 폼 렌더
POST (같은 URL, 폼 제출) ← 실행 시작
- 필드 구성 — 폼 트리거 노드의 formFields 로 입력 필드(텍스트/드롭다운/체크박스 등)를 정의합니다. → 폼 트리거
- 다단계 폼 — 워크플로우 중간에 폼 노드를 두면 1단계 제출 후 다음 페이지가 렌더링되는 다단계 흐름을 만들 수 있습니다. 마지막 제출까지 끝나면 나머지 노드가 실행됩니다.
- 서버 검증 — 필수 필드 누락 등은
400과 읽을 수 있는 메시지로 거부됩니다. - 다중 체크박스 — 같은 필드의 복수 선택은 배열로 전달됩니다.
- 완료(마지막) 폼 노드는 표시 전용 완료 화면입니다.
게이트웨이 뒤 엔진 인증에 대하여
게이트웨이는 요청을 프록시할 뿐이며, 인증 검증은 엔진(웹훅 노드 설정)이 강제합니다. 인증이 걸린 웹훅을 게이트웨이로 호출해도 403 이 나면 정상 동작입니다(자격 미제공).