Webhooks

ObjectOS はアウトバウンド Webhook に永続的な アウトボックス モデルを 使用します。Webhook プラグインが有効になっている場合、業務上の変更によって 配信行がキューに追加され、バックグラウンドのディスパッチャーがリトライ付きで 配信します。これにより、受信側が遅延したり利用できなかったりしても、元の トランザクションがブロックされることはありません。

Webhook の有効化

Webhook はオプションの機能です。デプロイされた ObjectOS イメージに @objectstack/plugin-webhooks が含まれている必要があり、アプリケーション アーティファクトが Webhook サブスクリプション（通常は sys_webhook オブジェクトのレコードとして）を登録する必要があります。

有効化すると、Console に 2 つのオブジェクトが表示されます。

配信のセマンティクス

• At-least-once（最低 1 回）。 一時的な障害の後に配信がリトライされる ことがあります。受信側は冪等である必要があります。
• 永続的。 配信は業務データベースに保存されるため、ObjectOS の再起動後も 保持されます。
• パーティション化。 各ディスパッチャーワーカーはアウトボックスの パーティションを取得するため、デプロイメントは二重配信なしで配信を水平 スケールできます。
• リトライ回数の上限あり。 失敗した配信は設定可能な上限までバックオフ 付きでリトライされます。リトライを使い切った行は調査のために sys_webhook_delivery に残ります。

署名

すべての配信には、受信側がルーティング、重複排除、検証できるように識別用の ヘッダーが含まれます。

X-Objectstack-Event:     <event type, e.g. data.record.created>
X-Objectstack-Delivery:  <delivery id — use as your idempotency key>
X-Objectstack-Attempt:   <attempt number, starting at 1>

Webhook サブスクリプションに secret が設定されている場合、ObjectOS は すべてのリクエストにも署名します。

X-Objectstack-Signature: sha256=<hex hmac>

署名は、生のリクエストボディに対して計算された HMAC-SHA256(secret, body) です。ペイロードを信頼する前に、受信側で検証 してください。

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(body, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

シークレットをローテーションするには、新しいシークレットで新しい サブスクリプションを発行し、移行期間中は両方を稼働させてから、古いものを 無効化します。

受信側に求められること

• 数秒以内に 2xx で応答してください。408、429、5xx のレスポンス （またはタイムアウト／トランスポートエラー）はリトライ可能で、バックオフ 付きでリトライされます。その他の 4xx は永続的な障害として扱われ、 それ以上のリトライなしで dead に移されます。
• ディスパッチャーは 2xx を確認するまで配信を成功とマークしません。 そのため、受信に失敗すると、その行は調査または再配信のために sys_webhook_delivery に残ります。
• 冪等にしてください。X-Objectstack-Delivery ヘッダー（配信 ID）または ペイロード内の独自のイベント ID で重複排除します。

障害への対処

何かが失敗した場合は次のとおりです。

1. sys_webhook_delivery で該当の行を確認します。status、 response_code、response_body、attempts が記録されています。
2. ObjectOS から受信側へのアウトバウンドネットワークアクセスを確認します。
3. 受信側が恒久的に変更された場合は、サブスクリプションの URL を更新し、 Console から行を再配信します。
4. インシデントレビューのために、監査ログ（sys_audit_log）には サブスクリプションの編集は記録されますが、ペイロードは記録されません。 ペイロードはアウトボックスに残ります。

運用のヒント

• Webhook URL にシークレットを入れないでください（クエリ文字列はログに 記録されます）。
• 専用の受信側ホスト名を使用すると、メインアプリに影響を与えることなく、 エッジでブロックして負荷を切り離すことができます。
• ディスパッチャーの遅延を監視してください。アウトボックスが増加し続ける 場合、通常は受信側が劣化していることを意味します。