Webhook のメンテナンス：ワーカー停止・エンドポイント無効化・削除の違い

下流システムだけをメンテナンスするなら、Webhook 受信側での署名検証と永続保存を続け、イベントを処理するワーカーを止める設計が基本です。UnifyPort のエンドポイントを無効化すると、設定を削除せず状態が inactive になります。削除はリソース自体を取り除きます。どちらも「一時停止後に欠落分を再配信する」機能としては文書化されていません。止めたい層に合わせて選んでください。

要点

• CRM、AI 処理、ワーカーの保守なら、永続的な受信を維持したまま業務処理を停止します。
• エンドポイントの無効化は、配信の空白期間が生じる可能性を理解したうえで行います。
• 削除は廃止のための操作であり、一時的なデプロイ用スイッチではありません。
• 503 を返しても保守時間は確保できません。UnifyPort の再試行はバックオフなしで即時実行されます。

3 つの操作を比較する

最初の行はアプリケーション設計の推奨事項です。残りの 2 つは UnifyPort が公開している管理操作です。

操作	変わるもの	利用者側で管理するもの
アプリケーションのワーカーを停止	コンシューマーが停止し、正常な受信側は永続保存を継続	キュー容量、保持期間、再開位置、副作用の冪等性
エンドポイントを無効化	状態が inactive になり、設定は残る	中断記録、再有効化の検証、欠落期間の調査
エンドポイントを削除	リソースがなくなる	必要になった場合の新規作成と検証

無効化のリファレンスは POST /v1/webhook-endpoints/{endpoint_id}/deactivate を定義しています。削除のリファレンスは DELETE /v1/webhook-endpoints/{endpoint_id} を定義し、成功時は 204 No Content を返します。

操作対象は Webhook エンドポイントです。アカウントのログアウト、ランタイムの停止、アプリケーションが受理済みの仕事の取り消しとは区別してください。すでに仕事を取得したワーカーは処理を完了する可能性があります。その副作用を止めるには、アプリケーション側の制御が必要です。

ワーカー停止を保守の境界にする

たとえば、LINE と WhatsApp の問い合わせを受け続けながら CRM 連携を更新する場合を考えます。これは設計例であり、実在顧客の成果報告ではありません。

受信経路を CRM から独立させます。

1. 生のリクエストバイト列を使って署名とタイムスタンプを検証する。
2. イベントを検証し、永続ストレージへコミットする。
3. 成功応答を返す。
4. 別のワーカーが CRM 書き込み、AI 呼び出し、通知を処理する。

コンシューマーを止める前に、保守中も保存先が利用できることを確認します。キュー増加量や保持期間の運用上限を決め、保存失敗時の担当者を明確にしてください。メモリ内の配列は、プロセス再起動に耐える保守用バッファではありません。

更新後は、コミット済みの処理状態から再開します。入口が 2xx を返したことだけを理由に、滞留ジョブを完了扱いにしてはいけません。Webhook-first 接続チェックリストは最初の保存境界を説明しています。保守ではさらに、コンシューマーの実行可否を別途制御します。

保存先自体の保守は、この設計だけでは解決できません。受信側とストレージの両方を停止する必要があるなら、検証済みの代替受信経路を用意するか、中断を明示して記録します。裏付けなく無停止収集を約束しないでください。

エラー応答は一時停止機能ではない

配信仕様では、接続エラーと 408、429、5xx が即時再試行の対象です。retry_policy.max_attempts は初回リクエスト後の再試行回数で、既定値は 3 です。バックオフはなく、Retry-After も適用されません。それ以外の 4xx は自動配信を停止し、イベントをデッドレター扱いにします。

そのため、デプロイ中に 503 を返し続けると、復旧まで待たせるのではなく試行回数を使い切る可能性があります。内容を捨てながら 200 を返すのはさらに危険です。永続的に受理していないデータを確認済みにしてしまいます。デッドレター状態も、公開された再配信操作の存在を保証しません。

保守中も署名検証を維持してください。空の signing_secret は署名を無効化する設定であり、配信を停止する設定ではありません。認証情報を変更するなら、独立した署名シークレットのローテーション手順を使い、エンドポイント廃止と混同しないでください。

意図的に無効化する場合の復旧条件

変更前にエンドポイント設定の取得で ID、URL、状態、購読イベント、署名状態、再試行設定を記録します。実際のシークレットは保護された設定に保管し、変更記録には書きません。依存する下流処理も洗い出します。

対象を無効化した後、設定を再取得して状態を確認します。操作時刻と結果は、アプリケーションのキュー状態とは別に記録してください。公開リファレンスは、処理中リクエストの排出完了や無効期間のイベント再配信を保証していません。成功応答からそのような性質を推測しないでください。

再開にはエンドポイント更新を使い、status を active にした確認済み設定を送ります。意図した URL、購読内容、再試行設定、空でない署名シークレットを維持します。サンプルの無効状態や署名なし設定を、そのまま本番に適用してはいけません。

設定を再取得し、signing_enabled: true を確認します。その後、接続済みメッセージングアカウントへ管理されたテストメッセージを送り、message.received の署名検証、永続保存、対象ワーカーの処理まで追跡します。これは新しいイベントの経路を検証するものであり、無効期間の復旧を証明するものではありません。

管理リクエストがタイムアウトした場合は、追加変更の前に現在の設定を調べます。秘密情報を含まない診断記録を残してください。受信が静かなことは無効化完了の証拠ではなく、再有効化の成功応答も業務処理完了の証拠ではありません。

削除と復旧の限界

エンドポイントが不要になったことと依存関係を確認してから削除します。成功応答に JSON 本文はありません。後から代替を作ることは新規構築であり、旧エンドポイントが受け取れなかったイベントの復元ではありません。

UnifyPort の非公式インターフェースは対応するメッセージングアカウントのイベントを正規化しますが、汎用 REST メッセージ履歴読み取り API や欠落ペイロードの再配信保証はありません。限定的な WhatsApp 履歴機能も、複数チャネルの保守復旧を保証するものではありません。

保存済み処理の再開時は、文書化された重複排除単位を使います。通常イベントの再試行は X-Device-Event-Id を再利用しますが、conversation.history のバッチはメッセージ単位でマージし、このヘッダーだけで全体を除外してはいけません。送信などの業務上の副作用にも独立した冪等性が必要です。

FAQ

無効化しても設定は残りますか？

はい。状態が inactive になり、エンドポイントは削除されません。ただし滞留データの保持や再配信の保証にはなりません。

AI 処理だけを止められますか？

アプリケーション側でそのコンシューマーを止め、受信側で検証と永続保存を続ける設計にできます。追加の UnifyPort API 設定ではありません。

デプロイごとに削除して作り直すべきですか？

通常は不要です。下流の保守ではコンシューマーを停止し、エンドポイントの中断が必要なら計画的に行います。削除は廃止の判断です。

次のステップと参考資料

配信仕様を読み、本番設定を変える前に「どの層を止めるか」を明文化してください。

製品資料の確認日：2026-10-06。

• Webhook エンドポイントの無効化
• Webhook エンドポイントの更新
• Webhook エンドポイントの削除
• 配信、確認応答、再試行