基盤ドキュメント

本プラットフォームの概念理解と基本仕様

Osiryn（オサイリン）中継インフラストラクチャは、外部プラットフォーム（決済代行システム、チャットツール等）から非同期に行われるWebhook通知イベントを中継・保護するためのエンタープライズ向けに特化したプロキシおよびキューイングシステムです。

この技術ドキュメントでは、本システムを安全かつ確実に自社インフラに統合するための技術仕様、セキュリティ要件、および各種プロトコルの実装詳細を定義します。

システムの全体的な責務 (アーキテクチャ定義)

当システムの第一の責務は「送信元からの情報の不可逆的な損失（データロスト）を絶対的に回避すること」にあります。自社システムの障害やデプロイ中のダウンタイムを前提とした上で、暗号検証と永続化処理をEdge層で完了させ、後段のシステムへの安定したデータ供給を担保します。

1. 処理フローと状態遷移

■ 着信および署名検証 (検証フェーズ)
発行された固定のエンドポイントURLに対するPOSTリクエストに対し、事前に登録された共有シークレット（Secret Key）を用いたHMAC-SHA256ハッシュ検証を定数時間比較を用いて実行します。正規の要求とみなされた場合のみ後続フェーズへ移行します。
■ 高速永続化 (永続化フェーズ)
受信生データおよびヘッダー群をKVSおよびD1データベースへ即座に記録します。記録が完了した段階で、本プラットフォームは送信元システムに対し HTTP 200 OK を直ちに応答し、送信元の未達リトライ制御を終了させます。
■ キューイング・流し込み (中継フェーズ)
バックグラウンドワーカーが、お客様の指定した目標の送信先（Target URL）へ非同期でHTTP/HTTPSリクエストを発行します。自社システムが HTTP 4xx/5xx エラーを返却し失敗した場合、指数関数的バックオフに基づく再試行制御へと移行します。

2. 初期導入のステップ（運用開始まで）

STEP 01

プロジェクト領域の作成

管理コンソールより、用途ごとの専用エンドポイントのアドレスを発行します。このURLがすべての受信のフロントドアとなります。

STEP 02

目標URLと署名鍵の登録

最終的な中継先となる自社サーバーのHTTPSアドレスと、セキュリティ担保のための暗号化シークレットキーを入力します。

STEP 03

送信元システム（SaaS等）の設定変更

StripeやGitHubなどのWebhook送信先設定画面において、従来の自社サーバーアドレスを「STEP 01で発行された専用エンドポイント」の手持ちURLへ差し替えます。
これにより、以降の一切のトラフィックが本プラットフォームを安全に経由するようになります。