OpenAPI の Webhook¶

🌐 AI と人間による翻訳

この翻訳は、人間のガイドに基づいて AI によって作成されました。🤝

原文の意図を取り違えていたり、不自然な表現になっている可能性があります。🤖

AI LLM をより適切に誘導するのを手伝うことで、この翻訳を改善できます。

英語版

アプリがある種のイベントを通知するために、データ付きで相手のアプリ（リクエスト送信）を呼び出す可能性があることを、API のユーザーに伝えたい場合があります。

これは、通常のようにユーザーがあなたの API にリクエストを送るのではなく、あなたの API（あなたのアプリ）が相手のシステム（相手の API、アプリ）にリクエストを送る、ということです。

これは一般にWebhookと呼ばれます。

Webhook の手順¶

通常の流れとして、まずあなたのコード内で、送信するメッセージ、すなわちリクエストの本文（ボディ）を定義します。

加えて、アプリがそれらのリクエスト（イベント）を送信するタイミングも何らかの形で定義します。

そしてユーザーは、アプリがそのリクエストを送るべきURLを（たとえばどこかの Web ダッシュボードで）定義します。

Webhook の URL を登録する方法や実際にリクエストを送るコードなど、これらのロジックはすべてあなた次第です。あなた自身のコードで好きなように実装します。

FastAPI と OpenAPI による Webhook のドキュメント化¶

FastAPI と OpenAPI を使うと、Webhook の名前、アプリが送信できる HTTP の操作（例: POST, PUT など）、アプリが送るリクエストのボディを定義できます。

これにより、ユーザーがあなたの Webhook リクエストを受け取るためのAPI を実装するのが大幅に簡単になります。場合によっては、ユーザーが自分たちの API コードを自動生成できるかもしれません。

情報

Webhook は OpenAPI 3.1.0 以上で利用可能で、FastAPI 0.99.0 以上が対応しています。

Webhook を持つアプリ¶

FastAPI アプリケーションを作成すると、webhooks という属性があり、ここで path operations と同様に（例: @app.webhooks.post()）webhook を定義できます。

Python 3.10+

from datetime import datetime

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Subscription(BaseModel):
    username: str
    monthly_fee: float
    start_date: datetime


@app.webhooks.post("new-subscription")
def new_subscription(body: Subscription):
    """
    When a new user subscribes to your service we'll send you a POST request with this
    data to the URL that you register for the event `new-subscription` in the dashboard.
    """


@app.get("/users/")
def read_users():
    return ["Rick", "Morty"]

🤓 Other versions and variants

Python 3.9+

from datetime import datetime

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Subscription(BaseModel):
    username: str
    monthly_fee: float
    start_date: datetime


@app.webhooks.post("new-subscription")
def new_subscription(body: Subscription):
    """
    When a new user subscribes to your service we'll send you a POST request with this
    data to the URL that you register for the event `new-subscription` in the dashboard.
    """


@app.get("/users/")
def read_users():
    return ["Rick", "Morty"]

定義した webhook は OpenAPI スキーマおよび自動生成される ドキュメント UI に反映されます。

情報

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 も表示されます: