Webhook 트리거

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

사용 시기

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

빠른 시작

출력 파라미터

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

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

요청 보내기

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

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 대신 내 설치의 주소를 사용하세요.

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

주소와 토큰

• 저장하면 주소가 만들어집니다. 노드를 추가하고 워크플로를 저장하면 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 트리거와 일정 트리거처럼 여러 트리거를 두고, 각 트리거가 자기 브랜치를 시작하게 할 수 있습니다.

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

크레딧

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

팁

• 이름을 맞추세요. 다른 시스템이 보내는 키 이름을 대소문자까지 정확하게 사용하세요.
• 요청 하나로 테스트하세요. 운영 중인 시스템을 연결하기 전에 curl로 요청을 하나 보내 보세요.
• 결과를 다시 보내세요. 워크플로 끝에 Webhook 출력을 두어 결과를 내 서버로 보내세요.
• 일정에 따라서도 실행하세요. 같은 워크플로를 타이머로 실행하려면 일정 트리거를 추가하세요.

전체 API는 Webhook을 읽어 보세요.