Appleの公式資料では、App Store Connect Webhooksはビルドアップロード状態、ベータ版ビルド状態、Appのバージョン状態など、複数のイベント領域を扱えます。公式のイベント種類一覧が示す範囲からも、単なる「アップロード成功通知」より広い仕組みだと分かります。

症状： 遠隔MacでIPAを送信できても、TestFlightで利用可能になったかを手動更新で確認している。 最短の解法： 2026年は「App Store Connect Webhooksで起動し、サーバーに状態を記録し、APIまたは管理画面で最終確認する」構成にしてください。Webhookだけを唯一の事実にせず、イベントID、App、バージョン番号、Build番号、受信時刻を保存します。

この手順は、アップロード後にProcessing、Failed、Completeなどを自動通知したい独立開発者、遠隔Macのビルドから状態回復までを管理したい担当者、同じリリース状況を共有したい小規模チーム向けです。単にXcodeでArchiveを作る方法や、JWT認証エラーの詳しい修理方法は扱いません。

1. 監視対象を「転送」「処理」「公開可能」に分ける

最初に、遠隔Mac上の処理とApple側の状態を分離します。Archive、Export、IPAの転送が完了しても、Appleによる処理が完了したとは限りません。また、処理済みのBuildがTestFlightでテスト可能になることと、Appのバージョンが審査待ち・公開済みになることも別の判断です。

Appleのビルドアップロード状態に関する公式説明を基準に、少なくとも次のような内部状態を持たせます。

  • build_uploading：遠隔Macが転送処理を実行中
  • uploaded：Apple側への転送が完了したことを確認
  • processing：Apple側でビルドを処理中
  • complete：ビルド処理が完了
  • failed：ビルド処理または提出に失敗
  • beta_available：TestFlightで利用可能かを確認済み
  • manual_review：自動判定を止め、人が確認する状態
独立開発者なら、processing、failed、complete、beta_availableの通知を優先します。小規模チームでは、通知だけでなく、誰が確認したか、次の操作が必要かまで記録してください。自動化の境界は、成功時の通知と記録までに置き、再アップロード、Buildの削除、公開フローの切り替えは原則として人の確認を挟みます。

**注意** 「Transporterの送信成功」は、TestFlightでテスト可能になった証拠ではありません。転送結果、Apple側の処理状態、ベータ版での利用可能状態を別々に扱わないと、成功通知を出したのにテストできないという誤判定が起きます。

2. 初回設定はApp Store Connectの入口から始める

App Store ConnectのUsers and Access、Integrations、Webhooks周辺で、対象App、Payload URL、Secret、イベント種類を設定します。画面上の権限や利用可能な項目はAppleの管理仕様に従い、担当者のロールで表示されない場合は、権限管理者に確認してください。AppleのWebhook管理手順では、配信履歴やイベント詳細の確認、条件に応じた再送も説明されています。

Webhookはアカウント全体の万能なイベントバスとして扱わないでください。単一Appを監視する設定と、複数Appを個別に管理する構成では、対象範囲、保存するBundle ID、通知先の分離方法が変わります。複数のAppを運用するなら、イベント受信後にApp識別子を検証し、別のAppの処理へ誤って流れないようにします。

受信エンドポイントの最低条件は次のとおりです。

  1. インターネットからHTTPSで到達できること。
  2. リクエスト本文と受信時刻を先に保存できること。
  3. 正常に受け取ったら、重い処理を待たせず応答できること。
  4. Secret、JWT、API Key、完全なAuthorization値をログへ書かないこと。
  5. 再送を想定して、同じイベントを複数回受け取れること。
Payload URLには、ここで公開できる実在のURLや、再利用可能なSecretを記載しません。運用時は環境変数やシークレット管理機能へ保存し、ログには<PAYLOAD_URL>、<WEBHOOK_SECRET>、<KEY_ID>のような置換値だけを残します。

3. 最初のイベントは保存、検証、冪等化の順で処理する

受信処理の順番を、いきなり「成功処理」から始めないでください。最初に原文を保存し、イベントIDを取り出し、検証できる状態を残します。次に送信元や署名、タイムスタンプ、イベント種類、対象Appを確認し、過去に同じイベントIDを処理していないか調べます。

Webhookの設定に関するApple公式ドキュメントを参照しながら、データベースには少なくとも次の項目を持たせます。

  • event_id：イベント単位の一意な識別子
  • event_type：Build、ベータ版、Appバージョンなどの種類
  • app_id：対象App
  • bundle_id：内部で照合するBundle ID
  • version：Appのバージョン番号
  • build_number：Build番号
  • received_at：受信した時刻
  • payload_hash：原文の照合用ハッシュ
  • processing_status：未処理、処理済み、要確認などの内部状態
同じイベントIDが再び届いたら、通知を二重送信せず、受信記録だけ更新します。イベントの到着順が前後した場合も、単純に「最後に届いたもの」を正しい状態とみなさず、イベント時刻、Build番号、API照会結果を使って判断します。

Buildの状態名やフィールドの意味は、独自の推測で固定しないでください。AppleのWebhookイベント型リファレンスと、ビルド状態の公式リファレンスを近くに置き、Appleが定義した値と、自社システムの内部状態を別の列で管理します。

4. 遠隔Macの発版処理を状態チェーンへ接続する

遠隔MacやMACGPUのMac環境をiOS打包サーバーとして使う場合でも、1つのジョブを「成功・失敗」の2値だけで記録しないでください。次のように、実行側とApple側の境界を分けます。

<
判断軸遠隔Macで記録する内容Webhook・APIで確認する内容次の判断
ArchiveScheme、バージョン、Build番号、終了結果まだ対象外失敗ならビルドログを確認
ExportIPA生成、Export結果、署名処理の結果まだ対象外失敗なら再アップロードせず原因確認
転送転送開始、転送終了、コマンド結果アップロードイベントの有無イベント未着なら照会へ
Apple処理実行側では確定不可Processing、Complete、FailedBuild番号を照合
TestFlight実行側では確定不可ベータ版Buildの状態APIまたは画面で再確認
公開・審査実行側では確定不可Appバージョンの状態人工確認を含めて進行
この表のポイントは、遠隔Macが「実行」を担当し、App Store Connect Webhooksが「変化を知らせる」ことです。最終的な状態確定は、イベントIDとBuild番号を使ってApp Store ConnectのAPIまたは管理画面へ戻します。

API照会を行う場合は、専用のAPI Keyを発行し、鍵の権限と保管場所を分離してください。App Store Connect API Keyの作成に関する公式説明を参照し、秘密鍵の全文をCIログやWebhook本文へ混ぜない構成にします。既存のAPI認証トラブルをこの手順で解決したことにはせず、認証は別の検証項目として扱います。

5. 配信失敗と重複通知を復旧可能にする

Webhookの配信状態がSuccessでも、業務処理まで完了したとは限りません。受信側が本文を保存できたか、イベントIDがデータベースに登録されたか、後続のAPI照会が成功したかを分けて記録します。PendingやFailed、ネットワークタイムアウト、サーバーの5xxは、配信履歴とイベント詳細から原因を確認します。

自動再試行してよいのは、一時的なネットワーク障害やサービス一時停止など、時間を置けば復旧する可能性があるものです。Secretの不一致、対象Appの誤り、必須情報の不足、無効なバイナリといった業務上の失敗は、同じ通知を無限に再送しても直りません。

復旧手順は次の順番にします。

  1. 配信履歴でSuccess、Pending、Failedを確認する。
  2. 対象イベントの詳細と<EVENT_ID>を保存する。
  3. 受信サーバーのHTTP応答、タイムアウト、5xxログを確認する。
  4. 必要ならAppleの画面から対象イベントを再送する。
  5. 再送前に冪等キーを確認し、同じ業務アクションを二度実行しない。
  6. APIまたはApp Store Connect画面でBuildとTestFlightの最終状態を確認する。
  7. 署名、合規情報、バイナリ不備が原因なら、構築ログへ戻って修正する。

**経験則** 回復ボタンを「再ビルド」と同じ場所に置かないでください。Webhookの再送、APIによる再照会、遠隔Macでの再実行は別操作です。再送だけで直る障害と、IPAを作り直す必要がある障害を分離すると、重複提出を防げます。

6. 初回の実発版で受け入れ確認を行う

最初の検証では、通常の開発用ビルドではなく、実際に公開手順で使う1件のiOSビルドを選びます。遠隔MacでArchive、Export、アップロードを実行し、App Store Connect側のイベント、通知、データベースの記録、人工確認までを1本のタイムラインに並べます。

受け入れ条件は、次のように具体化してください。

  • Archive開始時刻とBuild番号が残っている。
  • IPAの転送結果とWebhookイベントIDが関連付いている。
  • ProcessingとCompleteを別の状態として保存している。
  • TestFlightの利用可能状態をAPIまたは画面で確認している。
  • 同じイベントの再送で通知や公開処理が二重にならない。
  • Failedから手動確認へ遷移できる。
  • <WEBHOOK_SECRET>、<JWT_PRIVATE_KEY>、完全なトークンをログから除外している。
  • データベースの最終状態とApp Store Connect画面の表示が一致している。
Processingの経過時間だけを基準に、自動で再アップロードしないでください。異常と判断する条件は、対象Buildの状態、Apple側の表示、API照会結果、過去の同じ処理記録を合わせて決めます。Webhooksの配信がない場合も、イベントが存在しないと断定せず、配信履歴、App Store Connect画面、APIを順に確認します。

7. 長期運用では通知の代替経路を残す

Webhookを導入しても、メール通知や定期的なAPI照会をすぐに全廃しないでください。Webhookは即時性のある入口ですが、受信サーバーの停止、設定変更、イベントの取りこぼし、イベントの順序変更が起きたときの補助経路が必要です。

小規模チームでは、Slackなどへの通知より先に、誰でも見られる状態記録を整えることを優先します。最低限、対象App、バージョン、Build番号、現在状態、最後のイベントID、最終確認時刻、担当者、次の操作を一覧にしてください。

遠隔Macを7×24時間のiOS打包サーバーとして運用する場合は、Webhook受信サービスとMac上のビルドジョブを同じ障害として扱わないことが重要です。Macが停止している場合、Apple側の通知を受け取れても再実行はできません。逆にMacの転送が成功していても、Webhook受信サービスが停止していれば、最終状態の確認が遅れます。

そのため、遠隔MacのSSH切断後に継続実行する方法のような運用設計と、Webhook側の再送・API照会を別々に点検してください。常駐環境が必要かを判断する際は、MACGPUの遠隔Mac利用案内も比較材料になりますが、物理接続、長期の固定負荷、チームのアクセス管理が必要なら、自前の実機や別のCI構成が適する場合もあります。

よくある確認事項

FAQでは、Webhookを「通知」、APIとApp Store Connect画面を「確認」として整理しています。どちらか一方だけに依存せず、Build番号とイベントIDで両者を結び付けてください。

まとめ：遠隔Macは実行、Webhookは起点、APIは確認に使う

App Store Connect Webhooksを導入する価値は、アップロード後の変化を素早く検知し、独立開発者やチームへ同じ状態を届けられることです。ただし、Webhook単体を最終的な事実とみなすと、重複通知、順序の乱れ、TestFlight状態の誤判定に弱くなります。

現在の手動更新や単純なページ監視には、状態の取りこぼし、担当者ごとの判断差、遠隔Macの転送成功とTestFlight公開可能状態の混同という欠点があります。常時稼働するmacOS環境を自分で購入して維持する方法もありますが、初期費用、保守、電源・回線、障害時の復旧を自分で抱えることになります。

発版が一時的、検証中心、または小規模チームで常駐Macを持つほどではないなら、必要な期間だけMACGPUの遠隔Macを借り、Archiveからアップロードまでを実行させる構成が現実的です。7×24時間の継続ビルドが必要な場合だけ、月単位や四半期単位のレンタルを検討し、Webhook受信サービスとAPIによる確認を組み合わせてください。