Webhook でワークフローを開始する

ほかのサービスからリクエストが届いたときに、ワークフローを開始できます。Issue が作られたときの GitHub、支払いが完了したときの Stripe、送信されたときのフォーム、Zapier や Make がつなぐアプリなどです。お使いのコンピューターには公開アドレスがないため、リクエストは Kitewell のリレーに届き、リレーがコンピューターの Kitewell に渡します。ポートを開ける必要も、トンネルを用意する必要もありません。

Webhook は Kitewell Personal と Team の機能で、Kitewell が Dagu Cloud にサインインしている必要があります。

Webhook をオンにする

保存済みのワークフローを開き、スケジュールを選びます。実行タイミングのカードからも開けます。
Webhook の オンにする を選びます。少しすると URL が表示されます：https://hooks.kitewell.app/…
コピー を選び、リクエストを送るサービスに URL を貼り付けます。
テストリクエストを送信 を選ぶと、経路全体を試せます。Kitewell が自分の URL にリクエストを送り、ほかのリクエストと同じくリレーを通って戻ってきます。実際のリクエストと同じく実行が 1 回始まり、最近のリクエストでそのリクエストが開いて、届いた内容を確認できます。

オンにすると、実行タイミングのカードに Webhook オン と表示されます。URL を見られるのは、ワークフローを編集できる人だけです。API キーや接続済みのアプリからは読み取れません。

アシスタントにリクエストを使わせる

リクエストの中身の形を知らなくても使えます。

実際のサービスからリクエストを 1 件送らせます。たとえば GitHub でテスト用の Issue を作ります。
最近のリクエストで、そのリクエストの詳細を選び、届いた内容を確認します。
このリクエストからステップを作る を選びます。アシスタントがそのリクエストを前提に開きます。「Issue のタイトルと作成者を取り出して Slack に投稿して」のように、必要なことを書き足して送信します。

アシスタントはリクエストを自分で読んでステップを提案し、適用するまで何も保存しません。

ステップでリクエストを読む

リクエストごとに実行が 1 回始まり、実行履歴にはトリガーが Webhook と表示されます。ステップは、次の 2 つの環境変数からリクエストを読みます。

WEBHOOK_PAYLOAD：送られてきた本文そのもの。
WEBHOOK_HEADERS：ヘッダーの JSON。小文字の名前ごとに値のリストを持ちます（例：{"x-github-event":["issues"]}）。Authorization と Cookie は含まれません。

どちらも入力として宣言する必要はありません。JSON の本文から課題のタイトルなどの値を取り出すには、このリクエストからステップを作る でアシスタントに頼みます。値を取り出すステップが追加され、後のステップはその値を ${steps.issue.outputs.title} のような名前で読めます。AI のステップには、本文全体をプロンプトの文章として渡せます。

本文は送り手が送ったものなので、信頼できない入力として扱ってください。コマンドでは、環境変数から読みます。macOS のシェルでは "$WEBHOOK_PAYLOAD"、Windows の PowerShell では $env:WEBHOOK_PAYLOAD です。${env.WEBHOOK_PAYLOAD} や、そこから取り出した値を、コマンドの文字列に直接書かないでください。引用符がコードとして解釈されてしまいます。アシスタントはこれらの変数を知っているので、届くはずのリクエストを伝えてワークフローを作らせることもできます。

送り手を設定する

GitHub

リポジトリまたは Organization の 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 を指定してイベントの送信先を追加し、イベントを選びます。Slack アプリでは、Event Subscriptions に URL を貼り付けます。Zapier や Make では、URL に POST する Webhook のアクションを追加します。フォームのサービスには、たいてい Webhook や「URL に通知」の設定があります。

送り手を確かめる

URL を知っている人は誰でも、その URL にリクエストを送れます。本物の送り手が署名したリクエストだけで実行を始めるには、受け付けるリクエストの送信元 でその送り手を選びます。GitHub、Stripe、Slack、Standard Webhooks から選べます。URL を知っている人なら誰でも を選ぶと、確認をやめます。

GitHub：シークレットを作成 を選びます。Kitewell はシークレットを一度だけ表示するので、GitHub の Webhook の 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 のすべてのイベントを受け付けます。最近受信: には最近のリクエストのイベントが並び、クリックで追加できます。保存を選びます。空欄なら、すべてのイベントで実行が始まります。

イベントの名前は、送り手の名付け方に従います。GitHub ではイベントとアクションをドットでつないだもの、Stripe と Standard Webhooks の送り手では本文の type、Slack ではコールバックが運ぶイベントの種類です。

それ以外のイベントのリクエストや、イベントを名乗らないリクエストでは実行が始まらず、スキップ と表示されます。URL を確かめるだけの GitHub の ping も同じです。

コンピューターがスリープ中やオフラインのとき

コンピューターに届くかどうかにかかわらず、リレーはすぐに送り手に応答します。リクエストはリレーで最大 7 日間待ち、Kitewell が再び接続すると古い順に実行されます。1 台のコンピューターに対して待てるのは 1,000 件までで、それを超えると送り手には後で再送するよう伝えます。

結果	意味
実行を開始	リクエストで実行が始まりました。リレーが同じリクエストを 2 回送っても、実行は 1 回です。
失敗	実行をキューに入れられませんでした（プロジェクトのエンジンが停止しているときなど）。エンジンが処理中や復旧中のときは、Kitewell が 10 分間再試行してから失敗とします。
無視	有料プランが終わっているか、ワークフローがプラン外です。
却下	受け付けるリクエストの送信元で選んだ送り手の有効な署名がありませんでした。
スキップ	Webhook が受け付けないイベントのリクエストか、GitHub の ping です。

URL を秘密にする

Webhook が送り手を確かめる設定になっていなければ、URL を知っている人は誰でもワークフローを開始できます。パスワードと同じように扱ってください。

新しい URL を選ぶとすぐに置き換わり、古い URL は 404 を返します。古い URL を貼った場所すべてに、新しい URL を貼り直してください。
オフにする も同じく URL を止めます。もう一度オンにすると、新しい URL になります。

Webhook の URL は 1 台のコンピューターのものです。同じワークフローの Webhook をチームメンバーのコンピューターでオンにすると、そのコンピューター用の URL になります。バックアップから復元すると、Webhook はオフの状態から始まります。

制限

制限	値
リクエストの本文	512 KiB までのテキスト
URL ごとのリクエスト	1 分あたり 60 件
コンピューターを待つリクエスト	1,000 件、最大 7 日間

リレーの応答：

ステータス	意味
`202`	受け付けました。本文は `{"id": "…"}` です。
`404`	Webhook の 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 上の Kitewell のリレー（hooks.kitewell.app）を通過します。リレーはコンピューターが受け取るまで、最大 7 日間だけリクエストを保持し、各 URL の秘密の部分はハッシュとしてのみ保存します。コンピューターでは、本文はほかの実行の入力と同じく実行とともに、設定した保持期間だけ残ります。コンピューターの外に出るものを参照してください。

トラブルシューティング

「Kitewell のリレーから URL を取得しています…」が消えない。 Kitewell が Dagu Cloud にサインインしていて、コンピューターがオンラインか確認し、Webhook をオフにしてからオンにしてください。
新しい URL が 404 を返す。 Kitewell が新しい URL をリレーに伝えるまで、数秒待ってください。
GitHub からの本文をステップで解析できない。 GitHub の Webhook で Content type を application/json にしてください。
リクエストが失敗になる。 行に理由が表示されます。プロジェクトが停止している場合は、メニューバーまたはトレイのメニューから開始し、リクエストをもう一度送ってください。