如何与 OpenAPI 定义的 Webhook 进行交互？

Question

阅读 OpenAPI Webhook 规范时，我无法理解如何实现 OpenAPI 定义的 Webhook/与 OpenAPI 定义的 Webhook 交互。我的主要来源是：

• https://spec.openapis.org/oas/latest.html#openapi-object（规范，

  webhooks

  字段）
• https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.yaml（示例）

我们来看看这个例子（我删掉了不相关的部分）

openapi: 3.1.0
webhooks:
  newPet:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully

我的问题：

• 这是否意味着当此

  newPet

  事件发生时（据我所知，该事件的含义是根据规范的实现细节），该服务器可能会发送带有

  POST

  主体的

  Pet

  请求，并且期望得到带有

  200

  状态代码的响应？
  • 如果否，
    • 那这是什么意思？
  • 如果是，
    • 此请求发送到哪个 URL？
    • 此 API 的用户能否以某种方式注册此请求应发送到的 URL？
    • 如果此 API 的用户不再希望接收与

      POST

      事件相关的

      newPet

      请求，他们如何取消订阅？
    • 协议仍然是HTTP（我99%确定，只是为了安全起见）？

Answer 1

这是否意味着当此

newPet

事件发生时（据我所知，该事件的含义是根据规范的实现细节），该服务器可能会发送带有

POST

主体的

Pet

请求，并且期望得到带有

200

状态代码的响应？

是的。

此请求发送到哪个 URL？

此 URL 是在 API 外部的某个位置定义的。例如，API 供应商可以提供一个开发人员门户，开发人员可以在其中订阅他们需要的 Webhooks 并配置目标 URL。

此 API 的用户能否以某种方式注册此请求应发送到的 URL？

见上文。

如果该API的用户不再希望接收与newPet事件相关的POST请求，如何取消订阅？

见上文。 Webhook 订阅管理应该发生在 API 之外的某个地方。

协议仍然是 HTTP（我 99% 确定，只是为了安全起见）？

OpenAPI 规范没有提及这一点，但可以安全地假设 HTTP 或 HTTPS。一些供应商仅出于安全原因将传出 Webhook URL 限制为 HTTPS。

Answer 2

Webhooks 部分的 OpenAPI 3.1 规范描述中的以下句子帮助我澄清了 Webhooks 和回调之间的区别（强调我的）：

与回调功能密切相关，本节描述

通过 API 调用以外的方式发起的请求

，例如通过带外注册。