OpenAPI Webhooks

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

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

这通常被称为 Webhook。

Webhooks 步骤

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

你还会以某种方式定义你的应用将在哪些 时刻 发送这些请求或事件。

而 你的用户 会以某种方式（例如，在某个 Web 仪表盘中）定义你的应用应该发送这些请求的 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.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"]

你定义的 Webhooks 将最终出现在 OpenAPI 模式和自动 文档 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。