OpenAPI Webhooks¶

在某些情况下，您希望告知 API **用户**，您的应用可以调用*他们的*应用（发送请求），并附带一些数据，通常是为了**通知**某种类型的**事件**。

这意味着，与用户向您的 API 发送请求的正常流程相反，是**您的 API**（或您的应用）可以**向他们的系统**（他们的 API、他们的应用）**发送请求**。

这通常被称为 **webhook**。

Webhooks 步骤¶

正常流程是，您在代码中**定义**您将要发送的消息，即**请求体**。

您还以某种方式定义您的应用将在*何时*发送这些请求或事件。

而**您的用户**则以某种方式（例如在某个 Web 仪表板上）定义您的应用应该将这些请求发送到的**URL**。

关于如何注册 Webhooks URL 以及实际发送这些请求的代码的*所有逻辑*都取决于您。您可以按照自己的意愿在**自己的代码**中编写。

使用 FastAPI 和 OpenAPI 文档化 Webhooks¶

借助 FastAPI 和 OpenAPI，您可以定义这些 Webhooks 的名称、您的应用可以发送的 HTTP 操作类型（例如 POST、PUT 等）以及您的应用将发送的请求**体**。

这可以大大简化您的用户*实现他们的 API* 来接收您的**Webhook** 请求，他们甚至可能能够自动生成他们自己的 API 代码。

信息

Webhooks 在 OpenAPI 3.1.0 及以上版本中可用，FastAPI 0.99.0 及以上版本支持。

带 Webhooks 的应用¶

当您创建一个 FastAPI 应用时，有一个 webhooks 属性可用于定义*webhooks*，就像您定义*路径操作*一样，例如使用 @app.webhooks.post()。

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

您定义的 Webhooks 将最终出现在 **OpenAPI** schema 和自动生成的**文档 UI** 中。

信息

app.webhooks 对象实际上只是一个 APIRouter，这与您在多文件结构中组织应用时使用的类型相同。

请注意，对于 Webhooks，您实际上并没有声明一个*路径*（如 /items/），您传递的文本只是 Webhook 的一个**标识符**（事件的名称），例如在 @app.webhooks.post("new-subscription") 中，Webhook 的名称是 new-subscription。

这是因为预期*您的用户*将以其他方式（例如 Web 仪表板）定义他们希望接收 Webhook 请求的实际**URL 路径**。

检查文档¶

现在您可以启动您的应用，然后访问 http://127.0.0.1:8000/docs。

您将看到您的文档中有正常的*路径操作*，现在也包含一些 **webhooks**。