Deploy Hooks

既定では、Workers Builds は接続した Git リポジトリへのコミット push でビルドを起動します。Deploy Hooks は、ビルドを起動する別の方法です。各フックは一意の URL で、HTTP POST リクエストを受け取ると、1 つのブランチに対する手動ビルドを起動します。Deploy Hooks を使うと、Workers Builds を次のようなワークフローにつなげられます。

ヘッドレス CMS のコンテンツが変わったときに自動で再ビルドする
外部の cron サービスでスケジュールビルドする
特定の条件に応じて、カスタム CI/CD パイプラインからデプロイを起動する

Deploy Hook を作成する

Deploy Hook を作成する前に、Worker が Git リポジトリに接続されていることを確認してください。

Workers & Pages を開き、対象の Worker を選びます。
Workers & Pages を開く ↗
Settings > Builds > Deploy Hooks を開きます。
name を入力し、ビルドする branch を選びます。
Create を選び、生成された URL をコピーします。

Deploy Hook を起動する

ビルドを開始するには、Deploy Hook の URL へ HTTP POST リクエストを送ります。

curl -X POST "https://api.cloudflare.com/client/v4/workers/builds/deploy_hooks/<DEPLOY_HOOK_ID>"

Authorization ヘッダーは不要です。URL に含まれる一意の識別子が認証情報になります。

レスポンスの例:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "build_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "branch": "main",
    "worker": "my-worker"
  }
}

レスポンスの build_uuid は、ビルド状態の監視とログの取得に使えます。

ビルドを確認する

Deploy Hook を起動したあと、ダッシュボードで次を確認できます。

Deploy Hooks の一覧では、最後に起動された時刻が表示されます。
Worker のビルド履歴では、Triggered by 列にフック名と deploy hook ラベルが付き、Deploy Hook から始まったビルドだと分かります。

これらのビルドをプログラムから調べる場合は、Builds API リファレンスの List builds for a Worker を使います。フック起動のビルドは build_trigger_source: "deploy_hook" として記録されます。

CMS 連携

多くのヘッドレス CMS は、コンテンツ変更時に Deploy Hook URL を呼び出す webhook に対応しています。設定の流れはプラットフォーム共通です。

CMS の webhook または integrations の設定を開きます。
新しい webhook を作成し、送信先 URL に Deploy Hook URL を貼り付けます。
webhook を起動するイベントを選びます（例: 公開、非公開、更新）。

プラットフォーム固有の手順は、各 CMS のドキュメントを参照してください。webhook に対応している主なプラットフォームには、Contentful、Sanity、Strapi、Storyblok、DatoCMS、Prismic があります。

冪等性

同じ Deploy Hook が、前のビルドが完全に開始する前にもう一度起動された場合、Workers Builds は重複ビルドを作りません。進行中のビルドを返します。

外部システムが同じ Deploy Hook を短時間に 2 回送った場合:

最初のリクエストでビルドが作成されます。
そのビルドがまだ queued または initializing のあいだに 2 回目のリクエストが届いても、2 つ目のビルドは作成されません。
代わりに、既存の build_uuid を返し、already_exists を true にします。

保留中の既存ビルドを返す場合のレスポンス例:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "build_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "queued",
    "created_on": "2026-01-21T18:50:00Z",
    "already_exists": true
  }
}

先のビルドが initializing を過ぎると、以降の POST は通常どおり新しいビルドを作成します。そのため、webhook を再試行するシステムや、コンテンツ更新イベントがバーストするシステムでも、Deploy Hooks を安全に使えます。

例

Slack のスラッシュコマンドからデプロイする

Slack から /deploy コマンドを受け取り、ビルドを起動する Worker です。

export default {
	async fetch(request, env) {
		const body = await request.formData();
		const command = body.get("command");
		const token = body.get("token");

		if (token !== env.SLACK_VERIFICATION_TOKEN) {
			return new Response("Unauthorized", { status: 401 });
		}

		if (command === "/deploy") {
			const res = await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
			const { result } = await res.json();
			return new Response(`Build started: ${result.build_uuid}`);
		}

		return new Response("Unknown command", { status: 400 });
	},
};

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const body = await request.formData();
    const command = body.get("command");
    const token = body.get("token");

    if (token !== env.SLACK_VERIFICATION_TOKEN) {
      return new Response("Unauthorized", { status: 401 });
    }

    if (command === "/deploy") {
      const res = await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
      const { result } = await res.json<{ result: { build_uuid: string } }>();
      return new Response(`Build started: ${result.build_uuid}`);
    }

    return new Response("Unknown command", { status: 400 });
  },
};

スケジュールで再ビルドする

Cron Trigger で、1 時間ごとに再ビルドする Worker です。

export default {
	async scheduled(event, env) {
		await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
	},
};

export default {
  async scheduled(event: ScheduledEvent, env: Env): Promise<void> {
    await fetch(env.DEPLOY_HOOK_URL, { method: "POST" });
  },
};

セキュリティ上の注意

Deploy Hook URL は環境変数またはシークレットマネージャーに保存し、ソースコードや公開設定ファイルには置かないでください。
URL へのアクセスは、必要なシステムだけに制限します。
URL が漏れた、または不正利用の疑いがある場合は、すぐに Deploy Hook を削除して新しいものを作成してください。削除した時点で古い URL は使えなくなります。

認証付きトリガーに Builds API を使う

外部システムがカスタムヘッダーに対応している場合は、Authorization ヘッダーに API トークンを付けて手動ビルドエンドポイントを呼び出せます。トークン認証ができ、リクエストごとにブランチも選べます。手順は手動ビルドを起動するを参照してください。

制限

Deploy Hooks のレート制限は、Worker あたり 1 分に 10 ビルド、アカウントあたり 1 分に 100 ビルドです。Workers Builds の制限の全体は制限と料金を参照してください。