• 介绍
  • 主要特点
  • 监听事件和协调工作流程
• Webhooks API
  • Webhook
  • 事件
• 教程
  • 介绍
  • 先决条件
  • 准备环境
  • 创建应用程序
    • 初始化项目
    • 创建快速服务器
    • 添加回调验证处理程序
    • 添加事件授权
    • 定义数据模型
    • 事件处理
    • 部署
  • 创建Webhook
  • 触发iModel事件
• 接口
  • Event
    • 创建
    • 激活
    • 停用
    • 删除
    • 获取列表
    • 获取详细信息
  • Validation
    • 确认Webhook回调所有权

1. Webhooks 介绍

订阅 iTwins 中发生的事件，以便在应用程序中调用操作。

1.1. 主要特点

• 订阅事件并在事件发生时接收即时通知
• 创建事件驱动的工作流程
• 消除低效的事件轮询
• 提高自动化程度并集成多个系统

1.2. 监听事件和协调工作流程

Webhooks 允许应用程序订阅事件并且在事件发生时收到通知。应用程序指定回调 URL。当事件发生时，会向这个回调 URL 发送 POST 请求。例如，应用程序可以使用 Webhook 去监听 iModel 的变化，当在 push 模型的变更集时收到通知，然后执行一些其他操作。

2. Webhooks API

Webhooks API 允许您订阅在 iTwin 平台中发生的事件。简单来说，Webhook ，有时被称为“ HTTP 回调”，是应用程序相互通信的一种方式，可以消除任何手动工作。

2.1. Webhook

要使用 Webhook 您需要创建一个 API 才能接收 Webhook 事件。您需要提供一个称为 callbackUrl 的公共 API 终端节点，在您创建自己的 Webhook 后在其中接收事件。此外，您需要提供一份您感兴趣的事件类型的列表。当创建 Webhook 后，需要几秒钟时间等待 Webhook 准备好。

2.1.1. 停用

可以停用现有的 Webhook 以暂停发送事件，直到您再次激活它。这种方式下，你就不必删除原有的 Webhook 然后创建一个新的。

2.1.2. 到期

Webhook 有到期时间，到期时将停用。在创建 Webhook 之前，有需要的话您可以设置到期时间。若未设置到期时间，则默认情况下，Webhook 将在30天后到期。

2.1.3. 安全

Webhook 密钥

当 Webhook创建时，Webhook 密钥同时生成并发送回客户端。

{
  "webhook": {
    "id": "72a10fad-103d-4e23-9a43-a4ddf2ef61cc",
    "secret": "4eb25d308ef2a9722ffbd7a2b7e5026f9d1f2feaca5999611d4ef8692b1ad70d"
  }
}

在将事件转发到客户端之前，Webhook 密钥与整个请求体一起使用，以生成 HMAC-SHA256 签名，该签名包含在签名请求标头中。在对接收的事件执行任何操作之前，客户端应使用自己的 Webhook 密钥副本和请求体来处理授权过程，并在其末端生成另一个签名以验证事件源。如果两个签名相同，则应将事件作为授权签名接受，否则应忽略该事件。

2.1.4. Webhook 事件签名

Webhook 签名示例：sha256=a24a2e58912f4708f21eb043def1b1bcc0684b81a2e3feebe04ca558ff9830ce 签名的第一个部分（等号前）暗示了算法，第二部分是生成客户端尝试匹配的哈希。

2.1.5. 回调验证

创建 Webhook 后，会自动将 HTTP OPTIONS 验证请求发送到回调 URL。该请求包含 WebHook-Request-Origin 标头， 其中包含发送系统的源。客户端必须在响应中包含 WebHook-Request-Origin 标头的回复，该标头的值与 WebHook-Request-Origin 标头中提供的值相同，或者使用单星号字符（''），表示传递目标支持来自所有源的通知。OPTIONS 响应应当包括 Allow* 标头，指示允许POST方法。

如果客户端不支持，Webhook 回调仍然可以验证，但是不能超过创建后的2天。初始的验证请求包含 WebHook-Request-Origin 头部，此头部包含可以通过 HTTP GET 请求进行手动调用的 URL 。如果回调 URL 没有在2天内得到验证，Webhook 会被自动删除。

2.1.6. 支持的事件

iModels

• iModelDeletedEvent - 在删除相关 iModel 时触发.
• NamedVersionCreatedEvent - 当相关 iModel 创建新named version时触发.
• ChangesetPushedEvent - 当相关 iModel 有新的变更集push时触发.

2.2. 事件

2.2.1. iModel 事件

包括基本事件信息和详细信息。

Changeset Pushed Event

为 iModel 推送新变更集时触发的事件。

iModel Deleted Event

删除 iModel 时触发的事件。

Named Version Created Event

为 iModel 创建新命名版本时触发的事件。

3. 教程

3.1. 介绍

在本教程中，您将学会如何使用Webhooks REST API去创建和管理您的Webhooks。此外，您将学会如何验证Webhook签名并处理应用程序中收到的事件消息。

3.2. 先决条件

本教程假设您已具备：

• 有关Webhooks及其工作原理的基础知识
• 有关Web 应用程序部署的知识或使用 Heroku/Netlify的经验
• 已经在iTwin 平台上注册了自己的应用程序/客户端
  • 注册应用程序的步骤可以在此处找到
  • 请您确保您的应用程序/客户端与Webhooks API相关联，且具有webhooks:read 和 webhooks:modify 作用域
• 应用程序/客户端有权访问任何现有iModel，并且至少包含一个未在其上创建命名版本的变更集
  • 您可以运行synchronization去创建教程中描述的iModel。或者，您可以在Bentley提供的示例创建新的iModel。
• 有关为iModel创建命名版本的知识。
  • 可在此处找到有关如何创建命名版本的教程。

3.3. 准备环境

3.3.1. 所需材料

Node.js（14.x LTS版本） 此工具提供了计算机正确读取和呈现代码所需的后端 JavaScript 运行时。它还允许您运行 NPM 命令行

Git 这是常见的源代码控制系统。

推荐材料

Visual Studio Code 这是我们推荐的编辑器和调试器工具，用于开发iTwin.js应用程序。它是免费的，开源的，包括一个用于使用GIT的GUI.

Postman 如果你想直接测试REST API调用，你可以使用Postman或任何其他能够发送HTTP请求的解决方案。如果这样做，则需要授权令牌才能使请求正常工作。

Heroku 帐户 在本教程中，Heroku 将用于部署测试应用程序。

3.4. 创建应用程序

由于 Webhooks 通过 HTTP 请求发送事件，因此您需要运行一个公开公共 HTTP 终结点的应用程序 - 回调 URL。在本教程中，我们将使用 Node.js 和 Express 进行测试应用程序。

3.4.1. 初始化项目

要开始，请为应用程序创建新目录并执行以下初始化命令。这些命令将初始化新的 npm 项目、安装所需的依赖项并配置 typescript。初始化后，通过将 outDir 属性设置为“dist”来更新新生成的 tsconfig.json 文件。下一步将是更新 package.json 文件以更新应用程序入口点和启动脚本。完成后，项目已准备好进行下一步。

cd your-project
npm init -y
npm install express
npm install -D typescript @types/express
tsc --init

// tsconfig.json
"outDir":"dist"

// package.json
"main":"dist/index.js"
...
...
"scripts":{
  "start":"tsc && node dist/index.js"
}

[warning]如果您遇到“无法识别 tsc”的问题，请尝试全局安装 typescript “npm install typescript -g”。

3.4.2. 创建快速服务器

现在让我们开始实现应用程序。首先，在项目目录 src/index.ts 中创建一个新文件。这将是应用程序的起点。从侧面的示例中，您可以看到我们将有一个公共HTTP端点，它将接受 app.post("/events",() => {})的 POST 请求。这是因为事件消息是使用 POST 方法发送的。请注意，上面有一行 app.use(express.text({ type: "application/json" }))，它使服务器将具有 json 内容的请求视为文本，并且最初不会反序列化它们，因为在即将执行的步骤之一中，事件授权将需要原始有效负载。

// src/index.ts
import express from "express";

const app = express();
app.use(express.text({ type: "application/json" }));

app.post("/events", () => {
  // Handle the event
});

const port = 5000;
app.listen(port, () => {
  console.log("Application was started.");
});

3.4.3. 添加回调验证处理程序

在开始使用事件处理之前，首先我们需要确保通过传递回调 URL 验证来激活新创建的 Webhook。为了解决这个问题，我们需要再添加一个 HTTP 终结点，该终结点接受 OPTIONS 请求 app.options("/events", () => {})，并执行文档中所述的验证握手。

// src/index.ts
app.options("/events", async (req, res) => {
  const requestedOrigin = req.headers["webhook-request-origin"] as string;

  res.setHeader("allow", ["POST"]);
  res.setHeader("webhook-allowed-origin", requestedOrigin);
  res.sendStatus(200);
});

3.4.4. 添加事件授权

为了授权事件源，我们需要添加事件签名验证。事件签名是请求签名标头中包含的 HMAC-SHA256 字符串。对于验证，我们将使用 Node.js 加密实用程序，它基本上允许我们最终生成相同类型的签名。生成的签名和请求中包含的签名应匹配以通过授权。让我们通过创建新的函数函数 validateSignature（payload： string， signatureHeader： string） 来开始添加验证。作为第一个参数，它将需要原始请求有效负载，作为第二个参数，它将需要签名标头值。此函数还需要 Webhook 密钥，稍后我们将创建一个 Webhook。由于签名标头值还包含加密算法名称和由 = 分隔的签名值，因此我们需要将这些值提取到单独的变量 const [algorithm， signature] = signatureHeader.split("=") 中。然后在这一点上，使用所有现有的变量，我们可以生成一个签名crypto.createHmac(algorithm,secret).update(payload，"utf-8").digest("hex")。最后，我们需要检查两个签名是否匹配并返回结果。

// src/index.ts
import crypto from "crypto";
function validateSignature(payload: string, signatureHeader: string): boolean {
  // Replace with your own webhook secret later
  const secret = "4eb25d308ef2a9722ffbd7a2b7e5026f9d1f2feaca5999611d4ef8692b1ad70d";

  const [algorithm, signature] = signatureHeader.split("=");
  const generated_sig = crypto.createHmac(algorithm, secret).update(payload, "utf-8").digest("hex");

  return generated_sig.toLowerCase() === signature.toLowerCase();
}

3.4.5. 定义数据模型

在开始接收事件之前，我们需要为预期数据准备模型。您可以通过从 API 参考下载 API 定义文件来查找事件架构。在右侧选择首选架构类型，然后单击导出。现在，从这一点开始，创建一个新的文件 src/models.ts，并通过匹配架构来创建事件类型。

// src/model.ts

export type Event = {
  content: IModelEvent | NamedVersionCreatedEvent;
  contentType: string;
  enqueuedDateTime: string;
  messageId: string;
  subscriptionId: string;
};

export type IModelEvent = {
  imodelId: string;
  projectId: string;
};

export type NamedVersionCreatedEvent = {
  changesetId: string;
  changesetIndex: string;
  versionId: string;
  versionName: string;
} & IModelEvent;

3.4.6. 事件处理

现在，一切都准备好了，可以开始实现它了。首先，我们希望为没有事件签名标头或任何有效负载的任何请求返回 401 Unauthored，因为如果 (!signatureHeader || !req.body) res.sendStatus(401)，这些是通过验证所需的组件。如果请求确实具有这些组件，那么我们可以继续进行进一步的处理逻辑，并尝试使用我们在步骤2.3中定义的函数来验证事件签名，如果(!validateSignature（req.body，signatureHeader)) res.sendStatus(401)。如果验证失败，我们可以假设事件是从意外源发送的，并且也安全地返回 401 Unauthored。在其他情况下，当验证通过时，继续反序列化事件并对其类型做出相应的反应。

// src/index.ts
import { Event, NamedVersionCreatedEvent } from "./models";
app.post("/events", (req, res) => {
  const signatureHeader = req.headers["signature"] as string;
  if (!signatureHeader || !req.body) res.sendStatus(401);

  if (!validateSignature(req.body, signatureHeader)) {
    res.sendStatus(401);
  } else {
    const event = JSON.parse(req.body) as Event;
    switch (event.contentType) {
      case "NamedVersionCreatedEvent": {
        const content = event.content as NamedVersionCreatedEvent;
        console.log(`New named version (ID: ${content.versionId}, Name: ${content.versionName}) was created for iModel (ID: ${content.imodelId})`);
        break;
      }
      default:
        res.sendStatus(400); //Unexpected event type
    }
  }
});

3.4.7. 部署

要使此应用程序正常工作，您必须部署它才能公开访问。如果您对部署有任何偏好，请继续使用您自己的部署方法和平台。如果没有，您可以继续学习教程并使用 Heroku：

部署应用程序，创建新的 Heroku 应用程序并清空 Heroku Git存储库 https://devcenter.heroku.com/articles/git#for-a-new-heroku-app. 通过推送代码 https://devcenter.heroku.com/articles/git#deploying-code 进行部署。 使用 heroku 日志 --tail 来监视应用程序的行为。 部署并运行应用程序后，我们可以继续进行 Webhook 创建。

3.5. 创建 Webhook

Webhook 是应用向其他应用发送自动消息或信息的一种方式。在本例中，我们将为现有的 iModel 事件创建一个 Webhook。

3.5.1. Request

通过向 https://api.bentley.com/webhooks/imodels 发送 POST 请求来创建 iModel 事件的 Webhook。需要具有有效持有者访问令牌的授权标头。

“创建 iModel 事件 Webhook”操作的示例 HTTP 请求

POST https://api.bentley.com/webhooks/imodels HTTP/1.1
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

3.5.2. 请求正文

Webhook 创建具有 3 个必需属性：

• imodelId - 要接收哪些事件的相关 iModel ID。
• callbackUrl - 您希望在其中发送事件的应用程序的公共终结点。
• eventTypes - 要订阅的 iModel 事件类型的列表。
• expirationDateTime - （可选） Webhook 不再处于活动状态的日期和时间。如果未指定该值，Webhook 将在 30 天后过期。 有关详细信息，请参阅文档。

请求体示例

{
  "imodelId":"IMODEL_ID",
  "callbackUrl":"https://HOSTNAME/events",
  "eventTypes":[
    "NamedVersionCreatedEvent"
  ],
  "expirationDateTime":"2021-06-07T08:27:42Z"
}

[warning] 不要忘记将“IMODEL_ID”占位符值替换为现有的 iModel ID，将“HOSTNAME”占位符值替换为已部署的应用程序主机名

3.5.3. 响应

成功响应后，您将获得 Webhook 密钥，稍后需要验证收到的事件。创建的 Webhook 的位置将包含在响应位置标头值中。通常，您需要将 Webhook 位置或 ID 和机密存储在应用程序存储中，以便为接收事件做准备，但对于本教程，只需使用它来替换步骤 2.3 中函数 validateSignature 中的 const secret 值。

示例响应“位置”标头:

Location: https://api.bentley.com/webhooks/f6f3aff5-7e28-4874-a3ff-22dbc62d94c9

响应结果示例:

{
  "webhook":{
    "id": "b41adbb6-2ecc-4770-a626-1721dff5be1e",
    "secret":"4eb25d308ef2a9722ffbd7a2b7e5026f9d1f2feaca5999611d4ef8692b1ad70d"
  }
}

[warning] 请注意，不应与任何人共享 Webhook 密钥，而应将其视为私钥。

3.6. 触发 iModel 事件

由于我们专门为 NamedVersionCreatedEvent 事件类型创建了 Webhook，因此您需要手动触发此事件。使用“获取 iModel 变更集”操作。有关如何创建命名版本的详细说明，请参阅本教程。

创建命名版本后，将触发 Webhook 事件并将其发送到应用程序（回调 URL）进行进一步处理。如果已使用 Heroku 部署了测试应用程序，请使用 heroku logs --tail 命令监视应用程序日志，并等待捕获和处理事件。

4. API 接口

4.1. 创建 Webhook

POST https://api.bentley.com/webhooks/imodels

4.1.1. 事件类型

当前支持的 Webhook 事件类型：

• iModelDeletedEvent
• NamedVersionCreatedEvent
• ChangeSetPushedEvent

4.1.2. 安全

在创建 Webhook 时，正在生成 Webhook 密钥。在将事件转发到客户端之前，secret 与整个事件正文一起使用，以生成 HMAC-SHA256 签名，该签名包含在签名请求标头中。在对接收的事件执行任何操作之前，客户端应将其自己的机密副本与事件正文一起使用，并在其端生成另一个签名以验证事件源。如果两个签名相同，则事件应被接受为有效签名，否则应忽略。

4.1.3. 到期

创建 Webhook 时，可以指定到期日期时间，在此之后，Webhook 将被停用。如果未指定过期时间，Webhook 将在 30 天后自动过期。

4.1.4. 注意

iModel 删除后，Webhook 删除不会保留。删除iModel时，请确保也删除相关的 Webhook。

4.1.5. 认证

需要具有有效Bearer token的授权标头，用于作用域 webhook：modify。

有关授权以及如何获取访问令牌的更多文档，请访问 OAUTH2 授权页面。

4.1.6. 请求

• 请求头

• 请求体

• 示例

  {
    "imodelId": "00c76c84-7170-4962-9256-2fc6c2b28851",
    "callbackUrl": "https://some-event-callback.io/events",
    "expirationDateTime": "2021-06-07T08:27:42Z",
    "secret": "custom-secret-value",
    "eventTypes": [
        "iModelDeletedEvent",
        "NamedVersionCreatedEvent",
        "ChangeSetPushedEvent"
    ]
  }
  

4.1.7. 响应

• Response 202 Accepted 请求已接受以进行处理。

  {
   "webhook": {
       "id": "72a10fad-103d-4e23-9a43-a4ddf2ef61cc",
       "secret": "4eb25d308ef2a9722ffbd7a2b7e5026f9d1f2feaca5999611d4ef8692b1ad70d"
   }
  }
  

  请求头

• Response 401 Unauthorized 此响应表示请求缺少有效的身份验证凭据。可能未提供 Access Token、由错误的颁发者颁发、没有所需的作用域或请求标头格式不正确。

  {
    "error": {
        "code": "Unauthorized",
        "message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
    }
  }
  

• Response 404 Not Found 找不到指定的 iModel。

  {
    "error": {
        "code": "iModelNotFound",
        "message": "Requested iModel is not available."
    }
  }
  

• Response 422 Unprocessable Entity 422（不可处理的实体）状态代码表示由于客户端错误（例如，格式错误的请求语法），服务器无法处理请求。

      //MissingRequestBody
      {
        "error": {
          "code": "MissingRequestBody",
          "message": "Request body was not provided."
        }
      }
  
      //InvalidCreateWebhookRequest
      {
        "error": {
            "code": "InvalidCreateWebhookRequest",
            "message": "Cannot create a webhook. Make sure the request body is valid.",
            "details": [{
                    "code": "MissingRequiredProperty",
                    "message": "Required property is missing.",
                    "target": "imodelId"
                },
                {
                    "code": "MissingRequiredProperty",
                    "message": "Required property is missing.",
                    "target": "callbackUrl"
                },
                {
                    "code": "MissingRequiredProperty",
                    "message": "Required property is missing.",
                    "target": "eventTypes"
                },
                {
                    "code": "InvalidValue",
                    "message": "Provided 'eventTypes' value is not valid. It must be an array and contain at least one event type.",
                    "target": "eventTypes"
                },
                {
                    "code": "InvalidValue",
                    "message": "Provided 'eventTypes' value is not valid. It must contain at least one event type.",
                    "target": "eventTypes"
                },
                {
                    "code": "InvalidValue",
                    "message": "'invalid-event-name' is not valid event type.",
                    "target": "eventTypes"
                },
                {
                    "code": "InvalidValue",
                    "message": "Provided 'expirationDateTime' value is not valid. It must be a string in ISO-8601 format.",
                    "target": "expirationDateTime"
                },
                {
                    "code": "InvalidValue",
                    "message": "Provided 'callbackUrl' value is not valid. It must start with 'https://'.",
                    "target": "callbackUrl"
                }
            ]
        }
      }
  

• Response 429 Too many requests 此响应表示用户在给定的时间内发送了太多请求。

  {
      "error": {
          "code": "TooManyRequests",
          "message": "More requests were received than the subscription rate-limit allows."
      }
  }
  

  名称 | 描述 | :-|:- retry-after | 请求数超过客户端订阅的速率限制。

4.1.8. 定义

• 创建 Webhook 响应

Schema

  {
    "type": "object",
    "title": "Create Webhook Response",
    "description": "Webhook creation response.",
    "properties": {
        "webhook": {
            "type": "object",
            "description": "Contains accepted webhook properties",
            "properties": {
                "id": {
                    "type": "string",
                    "description": "Globally unique identifier of the webhook."
                },
                "secret": {
                    "type": "string",
                    "description": "Random unique secret string that will be used to compute an HMAC digest for authorized content distribution."
                }
            }
        }
    }
  }

• 创建 Webhook 名称 |类型 | 描述 | :-|:-|:- imodelId | 字符串 | 相关iModel 的标识符 eventTypes | 字符串[] | 请求的事件类型的列表 callbackUrl | 字符串 | 将发送 Webhook 事件的 URL。 expirationDateTime | 字符串 | Webhook 到期日期和时间。如果未提供，则默认为请求时间后 30 天。 secret | 字符串 | 用于事件签名验证的机密字符串。如果未提供，将自动生成。

• 错误

包含错误信息和更具体的错误的可选数组。

Schema

  {
    "type": "object",
    "description": "Contains error information and an optional array of more specific errors.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "details": {
            "type": "array",
            "description": "Optional array of more specific errors.",
            "items": {
                "$ref": "#/components/schemas/ErrorDetails"
            }
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误详情

包含错误信息。

Schema

  {
    "type": "object",
    "title": "Error Details",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误响应

提供处理请求时发生的错误的详细信息。请注意，客户端不得假定每个失败的请求都将生成此架构的对象，或者响应中的所有属性都将为非 null，因为该错误可能已阻止构造此响应。

Schema

  {
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ]
  }

4.2. 激活 webhook

POST https://api.bentley.com/webhooks/{id}/activate

此操作可用于激活已停用的 Webhook。已停用的 Webhook 不会将任何事件转发到回调，激活会再次启用此功能。

4.2.1. 身份验证

需要具有有效承载令牌的授权标头，用于作用域 webhooks：modify。

有关授权以及如何获取访问令牌的更多文档，请访问 OAUTH2 授权页面。

4.2.2. 请求

• 请求参数

• 请求头

• 请求体

• 示例

{
    "expirationDateTime": "2021-06-07T08:27:42Z"
}

4.2.3. 响应

• Response 202 Accepted 请求已接受以进行处理。
• Response 401 Unauthorized 此响应表示请求缺少有效的身份验证凭据。可能未提供 Access Token、由错误的颁发者颁发、没有所需的作用域或请求标头格式不正确。

  {
    "error": {
        "code": "Unauthorized",
        "message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
    }
  }
  

• Response 403 Forbidden 用户无权激活 Webhook。

  {
      "error": {
          "code": "InsufficientPermissions",
          "message": "The user has insufficient permissions for the requested operation."
      }
  }
  

• Response 404 Not Found 找不到指定的 Webhook。

  {
    "error": {
        "code": "WebhookNotFound",
        "message": "Requested webhook is not available."
    }
  }
  

• Response 422 Unprocessable Entity 422（不可处理的实体）状态代码表示由于客户端错误（例如，格式错误的请求语法），服务器无法处理请求。

      //InvalidActivateWebhookRequest
      {
        "error": {
            "code": "InvalidActivateWebhookRequest",
            "message": "Cannot activate a webhook. Make sure the request body is valid.",
            "details": [{
                "code": "InvalidValue",
                "message": "Provided 'expirationDateTime' value is not valid. It must be a string in ISO-8601 format.",
                "target": "expirationDateTime"
            }]
          }
      }
  
      //InvalidWebhookRequest
      {
        "error": {
        "code": "InvalidWebhookRequest",
        "message": "Webhook subscription '5885fb70-81c1-423b-b556-771b5ab4d55b' cannot be activated because it is already active."
        }
      }
  

• Response 429 Too many requests 此响应表示用户在给定的时间内发送了太多请求。

  {
      "error": {
          "code": "TooManyRequests",
          "message": "More requests were received than the subscription rate-limit allows."
      }
  }
  

4.2.4. 定义

• 激活webhook

Webhook 激活的其他属性。

Schema

  {
      "type": "object",
      "title": "Activate Webhook",
      "description": "Additional properties of webhook activation.",
      "properties": {
          "expirationDateTime": {
              "type": "string",
              "description": "Webhook expiration date and time. If not provided will default to 30 days after the request time."
          }
      }
  }

• 错误

包含错误信息和更具体的错误的可选数组。

Schema

  {
    "type": "object",
    "description": "Contains error information and an optional array of more specific errors.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "details": {
            "type": "array",
            "description": "Optional array of more specific errors.",
            "items": {
                "$ref": "#/components/schemas/ErrorDetails"
            }
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误详情

包含错误信息。

Schema

  {
    "type": "object",
    "title": "Error Details",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误响应

提供处理请求时发生的错误的详细信息。请注意，客户端不得假定每个失败的请求都将生成此架构的对象，或者响应中的所有属性都将为非 null，因为该错误可能已阻止构造此响应。

Schema

  {
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ]
  }

4.3. 停用 Webhook

POST https://api.bentley.com/webhooks/{id}/deactivate

此操作可用于停用 Webhook。已停用的 Webhook 不会将任何事件转发到回调。已停用的 Webhook 不会被删除，可以再次激活。

4.3.1. 身份验证

需要具有有效Bearer token的授权标头，用于作用域 webhooks：modify。

有关授权以及如何获取访问令牌的更多文档，请访问 OAUTH2 授权页面。

4.3.2. 请求

• 请求参数

• 请求头

4.3.3. 响应

• Response 202 Accepted 请求已接受以进行处理。
• Response 401 Unauthorized 此响应表示请求缺少有效的身份验证凭据。可能未提供 Access Token、由错误的颁发者颁发、没有所需的作用域或请求标头格式不正确。

  {
    "error": {
        "code": "Unauthorized",
        "message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
    }
  }
  

• Response 403 Forbidden 用户无权激活 Webhook。

  {
      "error": {
          "code": "InsufficientPermissions",
          "message": "The user has insufficient permissions for the requested operation."
      }
  }
  

• Response 404 Not Found 找不到指定的 Webhook。

  {
    "error": {
        "code": "WebhookNotFound",
        "message": "Requested webhook is not available."
    }
  }
  

• Response 422 Unprocessable Entity 422（不可处理的实体）状态代码表示由于客户端错误（例如，格式错误的请求语法），服务器无法处理请求。

    {
      "error": {
          "code": "InvalidWebhookRequest",
          "message": "Webhook subscription '5885fb70-81c1-423b-b556-771b5ab4d55b' cannot be deactivated because it is already deactivated."
      }
    }
  

• Response 429 Too many requests 此响应表示用户在给定的时间内发送了太多请求。

  {
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
  }
  

4.3.4. 定义

• 激活webhook

Webhook 激活的其他属性。

Schema

{
    "type": "object",
    "title": "Activate Webhook",
    "description": "Additional properties of webhook activation.",
    "properties": {
        "expirationDateTime": {
            "type": "string",
            "description": "Webhook expiration date and time. If not provided will default to 30 days after the request time."
        }
    }
}

• 错误

包含错误信息和更具体的错误的可选数组。

Schema

{
  "type": "object",
  "description": "Contains error information and an optional array of more specific errors.",
  "properties": {
      "code": {
          "type": "string",
          "description": "One of a server-defined set of error codes."
      },
      "message": {
          "type": "string",
          "description": "A human-readable representation of the error."
      },
      "details": {
          "type": "array",
          "description": "Optional array of more specific errors.",
          "items": {
              "$ref": "#/components/schemas/ErrorDetails"
          }
      }
  },
  "required": [
      "code",
      "message"
  ]
}

• 错误详情

包含错误信息。

Schema

{
  "type": "object",
  "title": "Error Details",
  "description": "Contains error information.",
  "properties": {
      "code": {
          "type": "string",
          "description": "One of a server-defined set of error codes."
      },
      "message": {
          "type": "string",
          "description": "A human-readable representation of the error."
      }
  },
  "required": [
      "code",
      "message"
  ]
}

• 错误响应

提供处理请求时发生的错误的详细信息。请注意，客户端不得假定每个失败的请求都将生成此架构的对象，或者响应中的所有属性都将为非 null，因为该错误可能已阻止构造此响应。

Schema

{
  "type": "object",
  "title": "Error Response",
  "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
  "properties": {
      "error": {
          "description": "Error information.",
          "$ref": "#/components/schemas/Error"
      }
  },
  "required": [
      "error"
  ]
}

4.4. 删除 Webhook

DELETE https://api.bentley.com/webhooks/{id}

认证

需要具有有效Bearer token的授权标头，用于作用域 webhook：modify。

有关授权以及如何获取访问令牌的更多文档，请访问 OAUTH2 授权页面。

4.4.1. 请求

• 请求参数

• 请求头

4.4.2. 响应

• Response 202 Accepted 请求已接受以进行处理。
• Response 401 Unauthorized 此响应表示请求缺少有效的身份验证凭据。可能未提供 Access Token、由错误的颁发者颁发、没有所需的作用域或请求标头格式不正确。

  {
    "error": {
        "code": "Unauthorized",
        "message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
    }
  }
  

• Response 403 Forbidden 用户无权删除 Webhook。

  {
      "error": {
          "code": "InsufficientPermissions",
          "message": "The user has insufficient permissions for the requested operation."
      }
  }
  

• Response 404 Not Found 找不到指定的 Webhook。

  {
    "error": {
        "code": "WebhookNotFound",
        "message": "Requested webhook is not available."
    }
  }
  

• Response 429 Too many requests 此响应表示用户在给定的时间内发送了太多请求。

  {
      "error": {
          "code": "TooManyRequests",
          "message": "More requests were received than the subscription rate-limit allows."
      }
  }
  

4.4.3. 定义

• 错误

包含错误信息和更具体的错误的可选数组。

Schema

  {
    "type": "object",
    "description": "Contains error information and an optional array of more specific errors.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "details": {
            "type": "array",
            "description": "Optional array of more specific errors.",
            "items": {
                "$ref": "#/components/schemas/ErrorDetails"
            }
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误详情

包含错误信息。

Schema

  {
    "type": "object",
    "title": "Error Details",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误响应

提供处理请求时发生的错误的详细信息。请注意，客户端不得假定每个失败的请求都将生成此架构的对象，或者响应中的所有属性都将为非 null，因为该错误可能已阻止构造此响应。

Schema

  {
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ]
  }

4.5. 获取用户的 Webhook 列表

GET https://api.bentley.com/webhooks/

4.5.1. 认证

需要具有有效Bearer token的授权标头，用于作用域 webhook：read。

有关授权以及如何获取访问令牌的更多文档，请访问 OAUTH2 授权页面。

4.5.2. 请求

• 请求头

4.5.3. 响应

• Response 200 OK OK

  {
   "webhooks": [{
           "id": "b6db0467-52ae-4ff5-a9af-851c8e59a543",
           "eventSource": "iModels",
           "isActive": false,
           "isValidated": true,
           "callbackUrl": "https://some-event-callback.io/events",
           "expirationDateTime": "2021-06-07T09:15:41.9426079Z"
       },
       {
           "id": "418fd669-e256-46f4-a891-732e4c745044",
           "eventSource": "iModels",
           "isActive": true,
           "isValidated": true,
           "callbackUrl": "https://some-event-callback.io/events",
           "expirationDateTime": "2021-07-31T11:56:22.9562857Z"
       }
   ]
  }
  

• Response 401 Unauthorized 此响应表示请求缺少有效的身份验证凭据。可能未提供 Access Token、由错误的颁发者颁发、没有所需的作用域或请求标头格式不正确。

  {
    "error": {
        "code": "Unauthorized",
        "message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
    }
  }
  

• Response 429 Too many requests 此响应表示用户在给定的时间内发送了太多请求。

  {
      "error": {
          "code": "TooManyRequests",
          "message": "More requests were received than the subscription rate-limit allows."
      }
  }
  

4.5.4. 定义

• Webhook

• 错误

包含错误信息和更具体的错误的可选数组。

Schema

  {
    "type": "object",
    "description": "Contains error information and an optional array of more specific errors.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "details": {
            "type": "array",
            "description": "Optional array of more specific errors.",
            "items": {
                "$ref": "#/components/schemas/ErrorDetails"
            }
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误详情

包含错误信息。

Schema

  {
    "type": "object",
    "title": "Error Details",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误响应

提供处理请求时发生的错误的详细信息。请注意，客户端不得假定每个失败的请求都将生成此架构的对象，或者响应中的所有属性都将为非 null，因为该错误可能已阻止构造此响应。

Schema

  {
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ]
  }

4.6. 获取 Webhook 详细信息

GET https://api.bentley.com/webhooks/{id}

返回 Webhook 的详细响应

4.6.1. 认证

需要具有有效Bearer token的授权标头，用于作用域 webhooks：read。

有关授权以及如何获取访问令牌的更多文档，请访问 OAUTH2 授权页面。

4.6.2. 请求

• 请求参数

• 请求头

4.6.3. 响应

• Response 200 OK OK

   {
     "webhook": {
         "id": "b6db0467-52ae-4ff5-a9af-851c8e59a543",
         "isActive": false,
         "isValidated": true,
         "callbackUrl": "https://some-event-callback.io/events",
         "expirationDateTime": "2021-06-07T09:15:41.9426079Z",
         "validationState": "Webhook endpoint was validated successfully.",
         "_links": {
             "imodel": {
                 "href": "https://api.bentley.com/imodels/24659f92-e858-4c92-b964-dcca921ccd28"
             }
         }
     }
   }
  

• Response 401 Unauthorized 此响应表示请求缺少有效的身份验证凭据。可能未提供 Access Token、由错误的颁发者颁发、没有所需的作用域或请求标头格式不正确。

  {
    "error": {
        "code": "Unauthorized",
        "message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
    }
  }
  

• Response 404 Not Found 找不到指定的 Webhook。

  {
    "error": {
        "code": "WebhookNotFound",
        "message": "Requested webhook is not available."
    }
  }
  

• Response 429 Too many requests 此响应表示用户在给定的时间内发送了太多请求。

  {
      "error": {
          "code": "TooManyRequests",
          "message": "More requests were received than the subscription rate-limit allows."
      }
  }
  

4.6.4. 定义

• Webhook 详细信息

• 错误

包含错误信息和更具体的错误的可选数组。

Schema

  {
    "type": "object",
    "description": "Contains error information and an optional array of more specific errors.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "details": {
            "type": "array",
            "description": "Optional array of more specific errors.",
            "items": {
                "$ref": "#/components/schemas/ErrorDetails"
            }
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误详情

包含错误信息。

Schema

  {
    "type": "object",
    "title": "Error Details",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误响应

提供处理请求时发生的错误的详细信息。请注意，客户端不得假定每个失败的请求都将生成此架构的对象，或者响应中的所有属性都将为非 null，因为该错误可能已阻止构造此响应。

Schema

  {
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ]
  }

4.7. 确认 Webhook 回调所有权

https://api.bentley.com/webhooks/confirm?id&key

如果客户端应用程序不支持所需的握手，则此操作可用于手动确认 Webhook 回调所有权。具有此操作所需的查询参数值的完全构造的 URL 可以在创建 Webhook 后发送到指定回调 URL 的自动验证请求标头 WebHook-Request-Callback 中找到。如果自动确认了 Webhook 回调所有权，则不应再使用此操作。

4.7.1. 认证

需要具有有效 Bearer token 的授权标头，用于作用域 webhooks：modify。

有关授权以及如何获取访问令牌的更多文档，请访问 OAUTH2 授权页面。

4.7.2. 请求

• 请求参数

• 请求头

4.7.3. 响应

• Response 204 No Content 确认了 Webhook 回调所有权。

• Response 401 Unauthorized 此响应表示请求缺少有效的身份验证凭据。可能未提供 Access Token、由错误的颁发者颁发、没有所需的作用域或请求标头格式不正确。

  {
    "error": {
        "code": "Unauthorized",
        "message": "Access denied due to invalid access_token. Make sure to provide a valid token for this API endpoint."
    }
  }
  

• Response 404 Not Found 找不到指定的 Webhook。

  {
    "error": {
        "code": "WebhookNotFound",
        "message": "Requested webhook is not available."
    }
  }
  

• Response 422 Unprocessable Entity 422（不可处理的实体）状态代码表示由于客户端错误（例如，格式错误的请求语法），服务器无法处理请求。

  {
    "error": {
        "code": "InvalidWebhookRequest",
        "message": "Webhook callback is already validated."
    }
  }
  

• Response 429 Too many requests 此响应表示用户在给定的时间内发送了太多请求。

  {
      "error": {
          "code": "TooManyRequests",
          "message": "More requests were received than the subscription rate-limit allows."
      }
  }
  

4.7.4. 定义

• Webhook 详细信息

• 错误

包含错误信息和更具体的错误的可选数组。

Schema

  {
    "type": "object",
    "description": "Contains error information and an optional array of more specific errors.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "details": {
            "type": "array",
            "description": "Optional array of more specific errors.",
            "items": {
                "$ref": "#/components/schemas/ErrorDetails"
            }
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误详情

包含错误信息。

Schema

  {
    "type": "object",
    "title": "Error Details",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        }
    },
    "required": [
        "code",
        "message"
    ]
  }

• 错误响应

提供处理请求时发生的错误的详细信息。请注意，客户端不得假定每个失败的请求都将生成此架构的对象，或者响应中的所有属性都将为非 null，因为该错误可能已阻止构造此响应。

Schema

  {
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ]
  }