웹후크로 워크플로 시작하기

다른 서비스가 요청을 보내면 워크플로를 시작할 수 있습니다. 이슈가 열릴 때 GitHub이, 결제가 성공할 때 Stripe가, 누군가 제출할 때 양식 서비스가, 또는 Zapier와 Make가 연결하는 앱이 요청을 보냅니다. 사용자의 컴퓨터에는 공개 주소가 없으므로, 요청은 Kitewell의 릴레이로 가고 릴레이가 컴퓨터의 Kitewell에 전달합니다. 열어야 할 포트도, 설정할 터널도 없습니다.

웹후크는 Kitewell Personal 및 Team 기능이며, Kitewell이 Dagu Cloud에 로그인되어 있어야 합니다.

웹후크 켜기

저장된 워크플로를 열고 일정을 선택하거나, 실행 시점 카드를 선택합니다.
웹후크에서 켜기를 선택합니다. 잠시 후 https://hooks.kitewell.app/… 형태의 URL이 나타납니다.
복사를 선택하고, 요청을 보내는 서비스에 URL을 붙여 넣습니다.
테스트 요청 보내기를 선택하면 전체 경로를 시험할 수 있습니다. Kitewell이 자기 URL로 요청을 보내고, 그 요청은 다른 요청과 똑같이 릴레이를 거쳐 돌아옵니다. 실제 요청처럼 실행을 하나 시작하며, 최근 요청에서 열려 무엇이 도착했는지 보여 줍니다.

그러면 실행 시점 카드에 웹후크 켜짐이 표시됩니다. 워크플로를 편집할 수 있는 사람만 URL을 볼 수 있습니다. API 키와 연결된 앱은 URL을 읽을 수 없습니다.

어시스턴트가 요청을 활용하게 하기

요청이 어떤 구조인지 몰라도 활용할 수 있습니다.

실제 서비스에서 요청을 하나 보내게 합니다. 예를 들어 GitHub에서 테스트용 이슈를 엽니다.
최근 요청에서 그 요청 옆의 세부 정보를 선택해 무엇이 담겨 왔는지 확인합니다.
이 요청으로 단계 만들기를 선택합니다. 어시스턴트가 그 요청을 바탕으로 열립니다. “이슈 제목과 이슈를 연 사람을 꺼내서 Slack에 올리기”처럼 필요한 내용을 이어서 적고 보내세요.

어시스턴트는 요청을 직접 읽고 단계를 제안하며, 적용하기 전까지는 아무것도 저장하지 않습니다.

단계에서 요청 읽기

요청 하나가 실행 하나를 시작하며, 실행 기록에는 계기가 웹후크로 표시됩니다. 단계는 두 환경 변수에서 요청을 읽습니다.

WEBHOOK_PAYLOAD에는 보내온 그대로의 본문이 들어 있습니다.
WEBHOOK_HEADERS에는 헤더가 JSON으로 들어 있습니다. 이름은 소문자이고, 이름마다 값 목록이 있습니다(예: {"x-github-event":["issues"]}). Authorization과 쿠키는 제외됩니다.

둘 다 입력으로 선언할 필요는 없습니다. JSON 본문에서 이슈 제목 같은 필드 하나를 꺼내려면 이 요청으로 단계 만들기로 어시스턴트에게 요청하세요. 어시스턴트가 필드를 꺼내는 단계를 추가하고, 이후 단계는 ${steps.issue.outputs.title}처럼 이름으로 그 값을 읽습니다. AI 단계는 본문 전체를 텍스트로 프롬프트에 넣을 수 있습니다.

본문은 보낸 쪽이 보낸 내용 그대로이므로 신뢰할 수 없는 입력으로 다루세요. 명령은 본문을 환경 변수에서 읽습니다. macOS 셸에서는 "$WEBHOOK_PAYLOAD", Windows PowerShell에서는 $env:WEBHOOK_PAYLOAD입니다. ${env.WEBHOOK_PAYLOAD}나 거기서 꺼낸 값을 명령 텍스트에 직접 쓰지 마세요. 그 안의 따옴표가 코드가 되어 버립니다. 어시스턴트는 이 변수들을 알고 있으니, 받게 될 요청을 알려 주고 워크플로를 만들어 달라고 요청하세요.

보내는 쪽 설정하기

GitHub

저장소 또는 조직에서 Settings → Webhooks를 열고 Add webhook을 선택합니다.
Payload URL에 URL을 붙여 넣습니다.
Content type을 application/json으로 설정합니다. GitHub의 기본값은 본문을 폼 데이터(payload=…)로 보내며, 이는 JSON이 아닙니다.
Which events would you like to trigger this webhook? 항목에서 Let me select individual events를 선택하고, 워크플로에 필요한 이벤트만 고릅니다. 다음 이벤트만으로 제외하지 않는 한, GitHub이 보내는 모든 이벤트가 실행을 시작합니다.
Kitewell이 GitHub의 서명을 확인하게 하려면, Kitewell이 만든 시크릿을 Secret에 붙여 넣습니다. 요청을 보낸 쪽 확인하기를 참고하세요.

GitHub의 Recent Deliveries 탭에는 요청마다 Kitewell의 응답이 표시되며, 릴레이가 요청을 받았으면 202입니다.

다른 서비스

HTTP POST를 보내는 서비스라면 어떤 것이든 됩니다. Stripe에서는 URL로 이벤트 대상(event destination)을 추가하고 이벤트를 고릅니다. Slack 앱에서는 Event Subscriptions에 URL을 붙여 넣습니다. Zapier나 Make에서는 URL로 POST하는 웹후크 작업을 추가합니다. 양식 서비스에는 보통 웹후크나 ‘URL로 알림’ 설정이 있습니다.

요청을 보낸 쪽 확인하기

URL을 가진 사람은 누구나 그 URL로 요청을 보낼 수 있습니다. 실제 발신자가 서명한 요청으로만 실행을 시작하려면 요청을 받을 발신자에서 그 발신자를 고르세요. GitHub, Stripe, Slack, Standard Webhooks 중에서 고를 수 있습니다. URL을 가진 누구나를 고르면 확인을 다시 끕니다.

GitHub: 시크릿 만들기를 선택합니다. Kitewell은 시크릿을 한 번만 보여 주니, GitHub 웹후크의 Secret에 붙여 넣으세요. 새 시크릿은 시크릿을 교체하며, 새 시크릿을 GitHub에 붙여 넣을 때까지 GitHub의 요청은 거부됩니다.
Stripe: 이벤트 대상의 서명 비밀(whsec_로 시작)을 서명 비밀에 붙여 넣고 저장을 선택합니다.
Slack: Slack 앱의 Basic Information에 있는 Signing Secret을 서명 비밀에 붙여 넣고 저장을 선택합니다. 이 컴퓨터에 연결할 수 없는 동안에도 Kitewell의 릴레이가 Slack의 URL 확인에 응답합니다.
Standard Webhooks: 발신자가 보여 주는 서명 비밀(whsec_로 시작)을 서명 비밀에 붙여 넣고 저장을 선택합니다.

유효한 서명이 없는 요청은 실행을 시작하지 않으며, 이유와 함께 거부됨으로 표시됩니다. Stripe, Slack, Standard Webhooks의 서명은 릴레이가 요청을 받은 시각으로부터 5분 이내에 만들어진 것이어야 합니다. 그래서 릴레이에서 기다리던 요청도 확인을 통과합니다. 테스트 요청 보내기의 요청에도 서명이 붙습니다.

일부 이벤트만 받기

다음 이벤트만에는 요청이 실행을 시작할 이벤트를 issues.opened, invoice.paid처럼 쉼표로 구분해 적습니다. 이름은 그 아래의 이벤트까지 포함합니다. issues는 issues.opened를 비롯한 모든 issues 이벤트를 받습니다. 최근 받은 이벤트: 옆에는 최근 요청의 이벤트가 표시되며, 클릭 한 번으로 추가할 수 있습니다. 저장을 선택하세요. 비워 두면 모든 이벤트가 실행을 시작합니다.

Kitewell은 이벤트 이름을 발신자가 부르는 방식대로 붙입니다. GitHub에서는 이벤트와 액션을 점으로 이은 이름, Stripe와 Standard Webhooks 발신자에서는 본문의 type, Slack에서는 콜백에 담긴 이벤트의 유형입니다.

그 밖의 이벤트에 관한 요청이나 이벤트 이름이 없는 요청은 실행을 시작하지 않으며 건너뜀으로 표시됩니다. URL만 확인하는 GitHub의 ping도 마찬가지입니다.

컴퓨터가 잠자기 상태이거나 오프라인일 때

릴레이는 컴퓨터에 연결할 수 있든 없든 발신자에게 즉시 응답합니다. 요청은 릴레이에서 최대 7일 동안 기다리다가, Kitewell이 다시 연결되면 오래된 것부터 실행됩니다. 컴퓨터 한 대당 최대 1,000건까지 기다릴 수 있으며, 그보다 많아지면 발신자에게 나중에 다시 시도하라고 응답합니다.

최근 요청

웹후크 섹션에는 최근 요청 20건이 표시됩니다. 각 요청이 도착한 시각, 발신자가 붙인 이름으로 본 요청의 내용(GitHub의 issues.opened, Stripe의 payment_intent.succeeded 등), 크기, 결과입니다. 목록은 열려 있는 동안 자동으로 갱신됩니다.

세부 정보는 요청을 엽니다. 읽기 쉽게 정리된 본문과 헤더가 각각 복사 버튼과 함께 표시되고, 이 요청으로 단계 만들기와 실행 보기 → 버튼도 있습니다. 실행을 시작하지 않은 요청은 대신 그 이유를 보여 줍니다. 본문은 실행과 함께만 보관되기 때문입니다.

결과	의미
실행 시작됨	요청이 실행을 시작했습니다. 릴레이가 같은 요청을 두 번 보내도 실행은 하나만 시작됩니다.
실패	실행을 대기열에 넣지 못했습니다. 예를 들어 프로젝트 엔진이 멈춰 있는 경우입니다. 엔진이 바쁘거나 복구 중이면 Kitewell이 먼저 10분 동안 재시도합니다.
무시됨	유료 플랜이 끝났거나, 워크플로가 플랜에 포함되지 않습니다.
거부됨	요청을 받을 발신자에서 고른 발신자의 유효한 서명이 요청에 없었습니다.
건너뜀	웹후크가 받지 않는 이벤트에 관한 요청이거나, GitHub의 ping입니다.

URL을 비공개로 유지하기

웹후크가 요청을 보낸 쪽을 확인하지 않는다면, URL을 가진 사람은 누구나 워크플로를 시작할 수 있습니다. 비밀번호처럼 다루세요.

새 URL은 즉시 URL을 교체하며, 이전 URL은 404로 응답합니다. 이전 URL을 넣어 둔 곳마다 새 URL을 붙여 넣으세요.
끄기도 같은 방식으로 URL을 멈춥니다. 웹후크를 다시 켜면 새 URL이 만들어집니다.

웹후크 URL은 컴퓨터 한 대에 속합니다. 팀원의 컴퓨터에서 같은 워크플로의 웹후크를 켜면 그 컴퓨터만의 URL이 생깁니다. 백업을 복원하면 웹후크는 꺼진 상태로 시작합니다.

한도

한도	값
요청 본문	텍스트 512 KiB
URL당 요청	분당 60건
컴퓨터를 기다리는 요청	1,000건, 최대 7일

릴레이의 응답은 다음과 같습니다.

상태	의미
`202`	받았습니다. 본문은 `{"id": "…"}`입니다.
`404`	웹후크 URL이 아니거나, 꺼졌거나 교체되었습니다.
`413`	본문이 512 KiB를 넘습니다.
`415`	본문이 UTF-8 텍스트가 아닙니다.
`429`	이번 1분 동안 요청이 60건을 넘었습니다. `Retry-After`에 적힌 초가 지난 뒤 다시 시도하세요.
`503`	이 컴퓨터를 기다리는 요청이 이미 1,000건입니다.

Windows에서는 본문이 약 30,000자를 넘으면 실행을 시작하지 못하고 요청이 실패로 표시될 수 있습니다. GitHub의 push 및 pull request 이벤트는 그 정도로 클 수 있습니다. 수정을 준비하고 있습니다.

유료 플랜이 끝나거나 워크플로가 더 이상 플랜에 포함되지 않으면, URL은 여전히 요청을 받지만 아무것도 시작하지 않으며 무시됨으로 표시됩니다. 다시 가입해도 새 URL은 필요 없습니다.

요청이 거쳐 가는 곳

요청은 Cloudflare에서 운영되는 hooks.kitewell.app의 Kitewell 릴레이를 거칩니다. 릴레이는 컴퓨터가 요청을 가져갈 때까지만, 최대 7일 동안 요청을 보관하며, 각 URL의 비밀 부분은 해시로만 저장합니다. 컴퓨터에서는 본문이 다른 실행 입력과 마찬가지로 실행과 함께, 설정한 보관 기간 동안 보관됩니다. 컴퓨터 밖으로 나가는 것을 참고하세요.

문제 해결

“Kitewell 릴레이에서 URL을 가져오는 중…”이 사라지지 않습니다. Kitewell이 Dagu Cloud에 로그인되어 있고 컴퓨터가 온라인인지 확인한 뒤, 웹후크를 껐다가 다시 켜세요.
새 URL이 404로 응답합니다. Kitewell이 릴레이에 새 URL을 알릴 때까지 몇 초 기다리세요.
단계가 GitHub에서 온 본문을 해석하지 못합니다. GitHub 웹후크에서 Content type을 application/json으로 설정하세요.
요청이 ‘실패’로 표시됩니다. 행에 이유가 나옵니다. 프로젝트가 멈춰 있다면 메뉴 막대 메뉴나 트레이 메뉴에서 시작한 다음, 요청을 다시 보내세요.