OpenAPI Webhooks¶

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

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

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

Webhooks の手順¶

通常、そのプロセスは、**あなたが**コードで送信するメッセージ、つまり**リクエストのボディ**を**定義する**ことです。

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

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

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

FastAPI と OpenAPI で Webhooks をドキュメント化する¶

FastAPI では、OpenAPI を使用して、これらの Webhook の名前、あなたのアプリが送信できる HTTP 操作のタイプ (例: `POST`、`PUT` など)、およびあなたのアプリが送信するリクエスト**ボディ**を定義できます。

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

情報

Webhooks は OpenAPI 3.1.0 以降で利用可能であり、FastAPI `0.99.0` 以降でサポートされています。

Webhooks を持つアプリ¶

FastAPI アプリケーションを作成すると、`webhooks` 属性があり、これを使用して**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**も表示されます。