Openhook

Openhook

AI エージェント向けのイベント受信トレイです。公開 URL を作成し、コールバックを待ち、届いた内容を確認して、タスクを続行できます。

Openhook は独自の HTTP、SMTP、権威 DNS キャプチャサーバーを運用しています。イベントは SQLite データベースに保存されます。外部の webhook サービスは使用しません。

試す、またはホストする

アカウントなしで無料の受信トレイを作成するか、エージェントを接続してください。オプションのホスト型 Pro では、受信トレイを永続化し、アカウントを復旧できます。現在の利用状況とプランをご覧ください。セルフホストは引き続き MIT ライセンスで提供され、Openhook アカウントやサブスクリプションは不要です。

実用的なレシピ：ローカル転送、GitHub のプッシュコールバック、Stripe のテストコールバック。

1 分以内に最初のコールバックを受信

Python 3 がインストールされている状態で、リポジトリをクローンし、使い捨てのサンプルを実行します。

git clone https://github.com/openhook-dev/openhook-inbox.git
cd openhook-inbox
python3 examples/first_callback.py

openhook.dev に無料の受信トレイを作成し、実際のコールバックを送信して元のバイト列を検証した後、受信トレイとペイロードを削除します。プライベートトークンはメモリ内に保持されます。このサンプルにはアカウント、API キー、Python の依存関係は不要です。削除後も、最小限の運用アクティビティメタデータは残ります。

エージェントスキルをインストール

Codex、Claude Code、その他の互換性のある Agent Skills クライアント向けです。

npx skills add openhook-dev/openhook-inbox --skill openhook

スキルのセットアップと権限では、MCP 接続、REST フォールバック、ローカル転送、プライベート受信トレイトークンの取り扱いについて説明しています。スキルをインストールしても、サーバーはインストールも起動もされません。

Gemini CLI にインストール

gemini extensions install https://github.com/openhook-dev/openhook-inbox --ref main

インストール後、Gemini CLI を再起動してください。この拡張機能はホスト型の https://openhook.dev/mcp エンドポイントに接続します。ローカルのキャプチャサーバーは起動しません。また、コールバックのテストワークフロー向けの Openhook エージェントスキルも含まれています。接続や使い捨ての受信トレイ作成に、Openhook アカウントや API キーは不要です。create_webhook が返すプライベートトークンは秘密にしてください。このトークンをツールの引数として指定しないと、その受信トレイの読み取りや削除はできません。ホスト型の永続受信トレイには、別途 Openhook アカウントキーが必要です。

エージェントに使い捨ての受信トレイを作成するよう依頼し、その公開 URL をテスト対象のシステムに渡してください。コールバックを受信できれば Openhook に届いたことが確認できます。ハンドラーが動作したことを確認するには、アプリケーションの状態を別途確認してください。

gemini extensions uninstall openhook-inbox で拡張機能を削除できます。

OpenCode を接続

このエントリをプロジェクトの opencode.json に統合してください（既存の設定は維持してください）。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openhook": {
      "type": "remote",
      "url": "https://openhook.dev/mcp",
      "enabled": true
    }
  }
}

接続を確認するには、そのプロジェクトから opencode mcp list を実行し、OpenCode に使い捨ての受信トレイを作成して、合成コールバックを確認するよう依頼します。使い捨ての受信トレイに Openhook アカウントは不要です。プライベートトークンを設定ファイルやコミット対象のファイルに含めないでください。送信元には公開コールバック URL だけを渡してください。内容を確認したら、テスト用の受信トレイを削除してください。Openhook で受信できても、アプリケーションのハンドラーがイベントを処理した証明にはなりません。

この設定は OpenCode 1.19.1 で正常に接続できました。これは MCP 接続を検証するものであり、モデル主導のエンドツーエンドワークフローを検証するものではありません。クライアントの設定については、OpenCode MCP のドキュメントをご覧ください。接続を解除するには、mcp.openhook エントリを削除するか、その enabled の値を false に設定してください。

実行する

チェックアウトから、uv をインストールし、自分のサーバーを起動します。

uv sync
uv run openhook --http

http://127.0.0.1:8788/app を開きます。ウェブサイト、キャプチャ API、Streamable HTTP MCP エンドポイントは、1つのサービスと1つの永続ストアを共有します。

MCP クライアントを http://127.0.0.1:8788/mcp に接続するか、 stdio には uv run openhook を使用します。ローカルの stdio プロセスと稼働中の HTTP プロセスは、 両方で同じ OPENHOOK_DATABASE を使用すると、同じデータベースを共有します。 HTTP コールバックを受信するには、HTTP プロセスが稼働している必要があります。同じ処理を自分のサーバーで確認するには、 python3 examples/first_callback.py --url http://127.0.0.1:8788 を実行します。 外部プロバイダーを使用するには、外部から到達可能なオリジンが必要です。localhost の例で確認できるのは、 ローカルサーバーが動作することだけです。

GitHub のリリースでは、 利用可能な場合、バージョン付きのソースと Python ディストリビューションが提供されます。openhook-mcp パッケージは現在 PyPI で公開されていません。パッケージインデックスからインストールできると想定せず、 ソースをチェックアウトするか、リリースアーティファクトを使用してください。

エージェントのワークフロー

1. create_webhook を呼び出します。非公開の ohk_ 管理トークンを保存します。
2. 返された公開 HTTP URL、メールアドレス、または DNS 名を送信元に伝えます。
3. 管理トークンを指定して wait_for_request を呼び出します。
4. イベントを確認して対応します。返された next_since カーソルを使って再接続します。

公開キャプチャアドレスからイベントを読み取ったり、削除したりすることはできません。管理トークンが漏えいした場合は、 rotate_webhook_token でローテーションします。ローテーション後も公開アドレスは変わりません。

匿名インボックスの有効期限は7日以内です。各インボックスには、最大1000件のイベントを保持できます。 上限に達すると、保持済みイベントを削除する代わりに、キャプチャは容量エラーを返します。 個々のイベントの上限は1 MBです。メールアドレスと DNS アドレスは、対応するリスナーが設定されている場合にのみ返されます。

ネイティブツール

29個のツールで、インボックスの作成、応答設定、トークンのローテーション、 イベントの確認、完全一致検索、メモ、JSON/CSV エクスポート、バイト列そのままのダウンロード、 HTTP/メールの待機、テストイベント、リンク/コードの抽出、コールバックの確認、 遅延応答、プロバイダーのサブスクリプション、削除、アクティビティ履歴に対応しています。生成されたツールリファレンスを参照してください。

永続的なアクティビティ履歴

受理されたすべての HTTP、メール、DNS の受信と、成功したローカル変更について、 状態変更と同じトランザクション内でアクティビティレコードが書き込まれます。重複した送信元からの配信にも レコードが作成されます。履歴には、メモ、応答設定、遅延応答、トークンのローテーション、 サブスクリプション、削除、有効期限切れが含まれます。get_webhook_activity で読み取るか、action: activity、 非公開の token、since カーソル、上限付きの limit を指定して POST /api/call を実行します。

最小限のアクティビティメタデータは、ペイロードの削除後や有効期限切れ後も保持されます。非公開トークン、 プロバイダーの認証情報、本文、メモ、署名シークレットは含まれません。既存のイベントにはインポート済みのマークが付けられます。 過去の変更履歴を再構成することはできません。アプリケーションはレコードを追記しますが、これは暗号学的に 改ざんを防止するログではありません。拒否されたキャプチャは、受理済みイベントとして保存されません。

configure_webhook で verification_secret を設定すると、HTTP の生の本文に SHA256 HMAC が必須になります。 Openhook は X-Openhook-Signature: sha256=… と GitHub の X-Hub-Signature-256 を受け付けます。署名が無効な場合、キャプチャ前に拒否されます。 Idempotency-Key と X-GitHub-Delivery により、インボックス内での再試行が重複排除されます。

?openhook_wait=1 を含む受信 URL は、エージェントの応答を最大20秒待ちます。 このようなリクエストを送信する前に、respond_to_next_request を開始してください。

設定

環境変数	用途
OPENHOOK_ORIGIN	公開オリジン。デフォルトは http://127.0.0.1:8788
OPENHOOK_DATABASE	SQLite のパス。デフォルトは data/openhook.sqlite3
OPENHOOK_EMAIL_DOMAIN	独自の受信メールドメイン。未設定の場合、SMTP は無効になります
OPENHOOK_SMTP_PORT	SMTP リスナー。デフォルトは 2525。公開ポート 25 にマッピングします
OPENHOOK_DNS_DOMAIN	独自の委任コールバックゾーン。未設定の場合、DNS は無効になります
OPENHOOK_DNS_PORT	UDP/TCP DNS リスナー。デフォルトは 5353。公開ポート 53 にマッピングします
OPENHOOK_DNS_ADDRESS	DNS の A レコード検索で返す IPv4 アドレス

SMTP は不明な受信箱宛てのメールを拒否し、メールを中継することはありません。DNS は設定されたゾーンに対してのみ応答し、再帰問い合わせは提供しません。

デプロイ

コアサービスには Dockerfile を使用します。ホスト型デプロイでは hosted ターゲットをビルドします。compose.dokploy.yaml は、別の Dokploy プロジェクトでそのイメージを選択します。Openhook のドメインをサービス openhook のポート 8788 に割り当てます。名前付きデータボリュームはリリース後も保持されます。デプロイに関する注意事項を参照してください。

プロバイダーの登録とローカル配信

register_github_webhook、register_stripe_webhook、または register_linear_webhook を呼び出すと、ネイティブ受信箱が作成され、送信元で登録されます。プロバイダー API の認証情報は一時的に使用され、保存されることはありません。キャプチャ前に生の署名が検証されます。Stripe と Linear では、リプレイ対策としてタイムスタンプも検証されます。受信箱の有効期限が切れる前に unregister_webhook を呼び出して、送信元の登録を解除してください。

ローカル配信では、OPENHOOK_TOKEN に非公開の受信箱トークンを設定してから、次を実行します。

uv run openhook-listen --forward http://127.0.0.1:8080/webhook
# Or wake an already configured local OpenClaw:
uv run openhook-listen --openclaw

OpenClaw への配信には OPENCLAW_HOOKS_TOKEN も必要です。配信先が指定されていない場合、リスナーはイベントを JSON として出力します。リスナーは HTTPS で外部へ接続し、配信が成功するとカーソルを保存し、配信に失敗すると再試行します。配信は少なくとも 1 回行われるため、受信側ではイベント ID による重複排除が必要です。配信先ごとに個別のカーソルがあるため、配信先とトークンごとにリスナーを 1 つ実行してください。マネージド SSH トンネルのプロビジョニングは含まれていません。

確認

ウェブサイトは、中央揃えのテキストインターフェースと、セルフホストされた Paper Mono v1.000 可変フォント、および承認済みの Openhook ロゴを使用します。公開ページとライブのツールスキーマは、JavaScript の実行前に HTML としてレンダリングされます。エージェントのエントリーポイントには /agents.md、/skill.md、/llms.txt、/llms-full.txt、/docs.md、/openapi.json があります。ウェブフックのデモでは、受信箱を作成し、実際のコールバックを送信して、キャプチャしたイベントを読み取ります。web/ の編集後は、アセットのバージョンを更新してください。

bun run build

uv run --all-packages --extra dev pytest
node --check web/assets/app.js

テストでは、ネイティブ HTTP キャプチャ、非公開トークンの分離、署名検証、冪等性、永続化、有効期限、MCP、および実際のローカル SMTP と UDP/TCP DNS を検証します。

MIT ライセンスです。必須のサードパーティ通知は THIRD_PARTY_NOTICES.md にあります。

ホスト型開発とコントリビューション

コアパッケージには課金アダプターが含まれておらず、運営者の決済情報やログイン認証情報を読み取りません。別途インストールする hosted/ パッケージでは、GitHub ID、取り消し可能なエージェントキー、所有者別の受信箱、検証済みの有料請求書に基づく利用権限が追加されます。設定、制限、テストモードの要件、ローンチの依存関係については、ホスト型運用を参照してください。このコードが存在することは、実際のマーチャントや有料ローンチを意味するものではありません。

コントリビューションとセキュリティ報告を参照してください。