OpenAPI Webhooks¶
在某些情况下，您希望告知 API 用户，您的应用可能会调用他们的应用（发送请求）并附带一些数据，通常是为了通知某种类型的事件。
这意味着不再是用户向您的 API 发送请求的正常流程，而是您的 API（或您的应用）可能会向他们的系统发送请求（发送到他们的 API、他们的应用）。
这通常被称为 webhook。
Webhooks 步骤¶
流程通常是您在代码中定义要发送的消息，即请求的正文。
您还会以某种方式定义您的应用将在哪些时刻发送这些请求或事件。
而您的用户会以某种方式（例如在某个 Web 仪表板中）定义您的应用应发送这些请求的 URL。
所有关于如何注册 webhook URL 以及实际发送这些请求的代码的逻辑都由您决定。您可以在自己的代码中按您希望的方式编写。
使用 FastAPI 和 OpenAPI 记录 webhooks¶
使用 FastAPI 和 OpenAPI，您可以定义这些 webhook 的名称、您的应用可以发送的 HTTP 操作类型（例如 POST、PUT 等）以及您的应用将发送的请求正文。
这可以大大简化用户实现其 API 以接收您的 webhook 请求的过程，他们甚至可能能够自动生成自己的部分 API 代码。
Info
Webhooks 在 OpenAPI 3.1.0 及更高版本中可用，由 FastAPI 0.99.0 及更高版本支持。
带有 webhooks 的应用¶
当您创建一个 FastAPI 应用程序时，有一个 webhooks 属性，您可以用它来定义 webhooks，就像您定义路径操作一样，例如使用 @app.webhooks.post()。
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 中。
Info
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：
