与父操作相关的可能的带外回调的映射。映射中的每个值都是一个路径项对象，它描述了一组可能由 API 提供者发起的请求和预期的响应。用于标识路径项对象的键值是在运行时计算的表达式，用于标识用于回调操作的 URL。要描述来自 API 提供者的传入请求，使其独立于其他 API 调用，请使用webhooks字段。

4.8.18.1 模式化字段

字段模式	类型	描述
{表达式}	路径项对象 引用对象	用于定义回调请求和预期响应的路径项对象或对它的引用。提供了完整示例。

此对象*可以使用 规范扩展 进行扩展。

4.8.18.2 键表达式

用于标识路径项对象的键是一个运行时表达式，可以在运行时 HTTP 请求/响应的上下文中进行计算，以标识用于回调请求的 URL。一个简单的例子可能是$request.body#/url。但是，使用运行时表达式可以访问完整的 HTTP 消息。这包括访问 JSON 指针[RFC6901]可以引用的主体任何部分。

例如，给定以下 HTTP 请求

POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 187

{
  "failedUrl" : "https://clientdomain.com/failed",
  "successUrls" : [
    "https://clientdomain.com/fast",
    "https://clientdomain.com/medium",
    "https://clientdomain.com/slow"
  ]
}

201 Created
Location: https://example.org/subscription/1

以下示例显示了各种表达式的计算方式，假设回调操作具有名为eventType的路径参数和名为queryUrl的查询参数。

表达式	值
$url	https://example.org/subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning
$method	POST
$request.path.eventType	myevent
$request.query.queryUrl	https://clientdomain.com/stillrunning
$request.header.content-Type	application/json
$request.body#/failedUrl	https://clientdomain.com/failed
$request.body#/successUrls/2	https://clientdomain.com/medium
$response.header.Location	https://example.org/subscription/1

4.8.18.3 Callback 对象示例

以下示例使用用户提供的queryUrl查询字符串参数来定义回调 URL。这是一个如何使用回调对象来描述与订阅操作相关的 WebHook 回调以启用 WebHook 注册的示例。

myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

以下示例显示了一个回调，其中服务器是硬编码的，但查询字符串参数是从请求主体中的id和email属性填充的。

transactionCallback:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed