OpenAPI Webhook¶

アプリが、通常は特定のイベントを通知するために、何らかのデータでユーザーのアプリを呼び出す（リクエストを送信する）可能性があることを 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 アプリケーションを作成すると、Webhook を定義するために使用できる webhooks 属性があります。これは、たとえば @app.webhooks.post() のように、パス操作を定義するのと同じ方法です。

Python 3.8 以降

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 にアクセスできます。

ドキュメントには通常の**パス操作**と、いくつかの**Webhook**も表示されます。