OpenAPI Webhooks¶

APIの**ユーザー**に、アプリが（リクエストを送信して） *ユーザー* のアプリを呼び出す可能性があることを伝える必要がある場合があります。通常は、何らかの種類の**イベント**を**通知**するためです。

これは、通常のユーザーがAPIにリクエストを送信するプロセスとは異なり、**API**（またはアプリ）が**ユーザーのシステム**（ユーザーのAPI、アプリ）に**リクエストを送信する**可能性があることを意味します。

これは通常、**Webhook**と呼ばれます。

Webhooksの手順¶

このプロセスは通常、コード内で送信するメッセージ（**リクエストのボディ**）を**定義**することから始まります。

アプリがそれらのリクエストやイベントを送信する**タイミング**も、何らかの方法で定義します。

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

WebhooksのURLを登録する方法と、それらのリクエストを実際に送信するためのコードに関するすべての**ロジック**は、ユーザー次第です。ユーザーは、好きなように**独自のコード**で記述します。

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

FastAPIでは、OpenAPIを使用して、これらのWebhooksの名前、アプリが送信できるHTTP操作の種類（例：POST、PUTなど）、およびアプリが送信するリクエスト**ボディ**を定義できます。

これにより、ユーザーは**Webhook**リクエストを受信するためのAPIを**実装**しやすくなり、独自のAPIコードの一部を自動生成できる可能性もあります。

情報

WebhooksはOpenAPI 3.1.0以降で使用でき、FastAPI 0.99.0以降でサポートされています。

Webhooksを使ったアプリケーション¶

FastAPIアプリケーションを作成すると、パスオペレーション（例：@app.webhooks.post()）を定義する場合と同じように、Webhooksを定義するために使用できるwebhooks属性があります。

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"]

定義したWebhooksは、OpenAPIスキーマと自動生成されたドキュメントUIに含まれます。

情報

app.webhooksオブジェクトは実際にはAPIRouterであり、複数ファイルでアプリを構成する場合に使用する方法と同じです。

Webhookでは、実際にはパス（例：/items/）を宣言していません。そこで渡すテキストはWebhookの識別子（イベント名）に過ぎません。例えば、@app.webhooks.post("new-subscription")では、Webhook名はnew-subscriptionです。

これは、ユーザーがWebhookリクエストを受け取る実際のURLパスを他の方法（例：ウェブダッシュボード）で定義することが想定されているためです。

ドキュメントを参照してください¶

これでアプリを起動し、http://127.0.0.1:8000/docsにアクセスできます。

ドキュメントに通常のパス操作に加え、いくつかのWebhookが表示されます。