OpenAPI Webhooks¶

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

这意味着与用户向您的 API 发送请求的常规流程不同，这次是您的 API（或您的应用）可能会向他们的系统（向他们的 API 或应用）发送请求。

这通常被称为 webhook。

Webhooks 步骤¶

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

您还需要以某种方式定义您的应用将在什么时刻发送这些请求或事件。

并且您的用户会以某种方式（例如在某个网页仪表盘中）定义您的应用应该向哪个 URL 发送这些请求。

关于如何注册 Webhook URL 以及实际发送这些请求的代码的全部逻辑都由您决定。您可以按照自己想要的方式在自己的代码中编写。

使用 FastAPI 和 OpenAPI 记录 Webhooks¶

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

这可以使您的用户更容易地实现他们的 API 以接收您的 webhook 请求，他们甚至可以自动生成部分自己的 API 代码。

信息

Webhooks 在 OpenAPI 3.1.0 及更高版本中可用，并由 FastAPI 0.99.0 及更高版本支持。

带有 Webhooks 的应用¶

当您创建 FastAPI 应用时，可以使用 webhooks 属性来定义 webhooks，其方式与定义 路径操作 相同，例如使用 @app.webhooks.post()。

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

您定义的 Webhooks 将会包含在 OpenAPI 模式和自动生成的文档 UI 中。

信息

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

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

这是因为通常您的用户会通过其他方式（例如网页仪表盘）定义他们希望接收 Webhook 请求的实际 URL 路径。

检查文档¶

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

您会看到文档中不仅有常规的 路径操作，现在还包含了一些 webhooks。