3.6 KiB
OpenAPI の Webhook
アプリがある種のイベントを通知するために、データ付きで相手のアプリ（リクエスト送信）を呼び出す可能性があることを、API のユーザーに伝えたい場合があります。
これは、通常のようにユーザーがあなたの API にリクエストを送るのではなく、あなたの API（あなたのアプリ）が相手のシステム（相手の API、アプリ）にリクエストを送る、ということです。
これは一般にWebhookと呼ばれます。
Webhook の手順
通常の流れとして、まずあなたのコード内で、送信するメッセージ、すなわちリクエストの本文（ボディ）を定義します。
加えて、アプリがそれらのリクエスト（イベント）を送信するタイミングも何らかの形で定義します。
そしてユーザーは、アプリがそのリクエストを送るべきURLを（たとえばどこかの Web ダッシュボードで）定義します。
Webhook の URL を登録する方法や実際にリクエストを送るコードなど、これらのロジックはすべてあなた次第です。あなた自身のコードで好きなように実装します。
FastAPI と OpenAPI による Webhook のドキュメント化
FastAPI と OpenAPI を使うと、Webhook の名前、アプリが送信できる HTTP の操作（例: POST, PUT など）、アプリが送るリクエストのボディを定義できます。
これにより、ユーザーがあなたの Webhook リクエストを受け取るためのAPI を実装するのが大幅に簡単になります。場合によっては、ユーザーが自分たちの API コードを自動生成できるかもしれません。
/// info | 情報
Webhook は OpenAPI 3.1.0 以上で利用可能で、FastAPI 0.99.0 以上が対応しています。
///
Webhook を持つアプリ
FastAPI アプリケーションを作成すると、webhooks という属性があり、ここで path operations と同様に（例: @app.webhooks.post()）webhook を定義できます。
{* ../../docs_src/openapi_webhooks/tutorial001_py310.py hl[9:12,15:20] *}
定義した webhook は OpenAPI スキーマおよび自動生成される ドキュメント UI に反映されます。
/// info | 情報
app.webhooks オブジェクトは実際には単なる APIRouter で、複数ファイルでアプリを構成する際に使うものと同じ型です。
///
Webhook では（/items/ のような）パスを宣言しているわけではない点に注意してください。ここで渡す文字列は webhook の識別子（イベント名）です。たとえば @app.webhooks.post("new-subscription") での webhook 名は new-subscription です。
これは、ユーザーが実際に Webhook リクエストを受け取りたいURL パスを、別の方法（例: Web ダッシュボード）で定義することを想定しているためです。
ドキュメントの確認
アプリを起動し、http://127.0.0.1:8000/docs にアクセスします。
ドキュメントには通常の path operations に加えて、webhooks も表示されます:
