OpenAPI Webhook

在某些情況下，您會想告知您的 API 使用者，您的應用程式可以呼叫他們的應用程式（發送請求）並附帶一些資料，通常是為了通知某種類型的事件。

這表示，不同於使用者向您的 API 發送請求的正常流程，而是您的 API（或您的應用程式）會向他們的系統（他們的 API、他們的應用程式）發送請求。

這通常稱為Webhook。

Webhook 步驟

通常的流程是，您在程式碼中定義要發送的訊息，也就是請求的主體。

您也以某種方式定義您的應用程式將在哪些時刻發送這些請求或事件。

而您的使用者則以某種方式（例如在某個網頁儀表板中）定義您的應用程式應該發送這些請求的網址。

所有關於如何註冊 Webhook 網址的邏輯以及實際發送這些請求的程式碼都由您決定。您可以用自己的程式碼以任何您想要的方式撰寫。

使用FastAPI 和 OpenAPI 文件化 Webhook

使用FastAPI 和 OpenAPI，您可以定義這些 Webhook 的名稱、您的應用程式可以發送的 HTTP 操作類型（例如 POST、PUT 等）以及您的應用程式將發送的請求主體。

這可以讓您的使用者更輕鬆地實作他們的 API 來接收您的Webhook 請求，他們甚至可以自動產生一些自己的 API 程式碼。

資訊

Webhook 在 OpenAPI 3.1.0 及更高版本中可用，FastAPI 0.99.0 及更高版本支援。

具有 Webhook 的應用程式

當您建立FastAPI 應用程式時，有一個 webhooks 屬性可以用來定義Webhook，就像定義路徑操作一樣，例如使用 @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"]

您定義的 Webhook 最終會出現在OpenAPI 結構描述和自動文件 UI 中。

資訊

app.webhooks 物件實際上只是一個 APIRouter，與您在使用多個檔案建構應用程式時使用的類型相同。

請注意，使用 Webhook 時，您實際上並沒有宣告路徑（例如 /items/），您傳遞的文字只是 Webhook 的識別碼（事件名稱），例如在 @app.webhooks.post("new-subscription") 中，Webhook 名稱為 new-subscription。

這是因為預期您的使用者會以其他方式（例如網頁儀表板）定義他們想要接收 Webhook 請求的實際網址路徑。

查看文件

現在您可以啟動您的應用程式並前往 http://127.0.0.1:8000/docs。

您會看到您的文件中包含正常的路徑操作，現在還有一些Webhook