OpenAPI Webhooks

有时，您希望告知API的**用户**，您的应用可以调用*他们的*应用（发送请求）并传递一些数据，通常是为了**通知**某种**事件**。

这意味着，与通常的用户向您的API发送请求的过程不同，现在是**您的API**（或您的应用）可以**向他们的系统**（向他们的API，他们的应用）发送请求。

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

Webhooks步骤

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

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

而**您的用户**则以某种方式（例如在某个网页仪表板中）定义您的应用应发送这些请求的**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。

这是因为预期**您的用户**会以某种其他方式（例如通过网页仪表板）定义他们希望接收webhook请求的实际**URL路径**。

查看文档

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

您将看到您的文档中既有正常的*路径操作*，现在还有一些**webhooks**：