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 事件
包括基本事件信息和详细信息。
名称 | 类型 | 描述 |
---|---|---|
content | 其中:changeset-pushed-event ,imodel-deleted-event ,named-version-created-event |
事件内容 |
contentType | 字符串 | iModel 事件 Webhook 事件类型。 |
enqueuedDateTime | 字符串 | 事件排队的日期和时间。 |
messageId | 字符串 | 事件消息ID |
subscriptionId | 字符串 | Webhook ID |
Changeset Pushed Event
为 iModel 推送新变更集时触发的事件。
名称 | 类型 | 描述 |
---|---|---|
briefcaseId | 字符串 | Briefcase ID |
changesetId | 字符串 | 变更集ID 是一个40个字符长度的SHA1 哈希,用于验证变更集。变更集ID 是根据其父级的ID 及其内容生成的 |
changesetIndex | 字符串 | 变更集的索引(递增,但不一定是连续的) |
imodelId | 字符串 | iModel 的全局唯一标识符 |
projectId | 字符串 | iModel 所属项目的全局唯一标识符 |
iModel Deleted Event
删除 iModel 时触发的事件。
名称 | 类型 | 描述 |
---|---|---|
imodelId | 字符串 | iModel 的全局唯一标识符 |
projectId | 字符串 | iModel 所属项目的全局唯一标识符 |
Named Version Created Event
为 iModel
创建新命名版本时触发的事件。
名称 | 类型 | 描述 |
---|---|---|
changesetId | 字符串 | 变更集ID 是一个40个字符长度的SHA1 哈希,用于验证变更集。变更集ID 是根据其父级的ID 及其内容生成的 |
changesetIndex | 字符串 | 变更集的索引(递增,但不一定是连续的) |
imodelId | 字符串 | iModel 的全局唯一标识符 |
projectId | 字符串 | iModel 所属项目的全局唯一标识符 |
versionId | 字符串 | 命名版本的全局唯一标识符。 |
versionName | 字符串 | 命名版本的显示名称 |
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 接口
类型 | 请求URL | 标题 | 标签 |
---|---|---|---|
POST | /webhooks/{id}/activate | 激活Webhook | Events |
GET | /webhooks/confirm?id&key | 确认Webhook回调所有权 | Validation |
POST | /webhooks/imodels | 创建Webhook | Events |
POST | /webhooks/{id}/deactivate | 停用Webhook | Events |
DELETE | /webhooks/{id} | 删除Webhook | Events |
GET | /webhooks/ | 获取用户的Webhook列表 | Events |
GET | /webhooks/{id} | 获取Webhook的详细信息 | Events |
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. 请求
- 请求头
名称 | 必填? | 描述 |
---|---|---|
Authorization | 是 | 具有 webhooks:modify 作用域的 OAuth access token |
Accept | 否 | 推荐设置为application/vnd.bentley.itwin-platform.v1+json |
- 请求体
名称 | 类型 | 必填? | 描述 |
---|---|---|---|
iModelId | 字符串 | 是 | 相关的 iModel 标识 |
eventTypes | 字符串[] | 是 | 请求的事件类型的列表 |
callbackUrl | 字符串 | 是 | 将发送 Webhook 事件的 URL。 |
expirationDateTime | 字符串 | 否 | Webhook 到期日期和时间。如果未提供,则默认为请求时间后 30 天。 |
secret | 字符串 | 否 | 用于事件签名验证的机密字符串。如果未提供,将自动生成。 |
- 示例
{ "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" } }
名称 | 描述 |
---|---|
Location | 资源位置 |
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 此响应表示用户在给定的时间内发送了太多请求。
名称 | 描述 | :-|:- retry-after | 请求数超过客户端订阅的速率限制。{ "error": { "code": "TooManyRequests", "message": "More requests were received than the subscription rate-limit allows." } }
4.1.8. 定义
- 创建
Webhook
响应
名称 | 类型 | 描述 |
---|---|---|
webhook.id | 字符串 | Webhook 的全局唯一标识符 |
webhook.secret | 字符串 | 随机唯一机密字符串,将用于计算授权内容分发的 HMAC 摘要 |
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 | 字符串 | 用于事件签名验证的机密字符串。如果未提供,将自动生成。错误
包含错误信息和更具体的错误的可选数组。
名称 | 类型 | 描述 |
---|---|---|
code | 字符串 | 服务器定义的一组错误代码之一 |
message | 字符串 | 错误的人类可读表示形式。 |
details | ErrorDetails[] | 更具体的错误的可选数组。 |
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"
]
}
- 错误详情
包含错误信息。
名称 | 类型 | 描述 |
---|---|---|
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
,因为该错误可能已阻止构造此响应。
名称 | 类型 | 描述 |
---|---|---|
error | Error | 错误信息 |
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. 请求
- 请求参数
名称 | 位置 | 必填? | 描述 |
---|---|---|---|
id | 模板 | 是 | Webhook ID |
- 请求头
名称 | 必填? | 描述 |
---|---|---|
Authorization | 是 | 具有 webhooks:modify 作用域的 OAuth 访问令牌 |
Accept | 否 | 推荐设置为application/vnd.bentley.itwin-platform.v1+json |
- 请求体
名称 | 类型 | 必填? | 描述 |
---|---|---|---|
expirationDateTime | 字符串 | 否 | Webhook 到期日期和时间。如果未提供,则默认为请求时间后 30 天。 |
- 示例
{
"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." } }
名称 | 描述 |
---|---|
retry-after | 请求数超过客户端订阅的速率限制。 |
4.2.4. 定义
- 激活webhook
Webhook 激活的其他属性。
名称 | 类型 | 描述 |
---|---|---|
expirationDateTime | 字符串 | Webhook 到期日期和时间。如果未提供,则默认为请求时间后 30 天。 |
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."
}
}
}
- 错误
包含错误信息和更具体的错误的可选数组。
名称 | 类型 | 描述 |
---|---|---|
code | 字符串 | 服务器定义的一组错误代码之一 |
message | 字符串 | 错误的人类可读表示形式。 |
details | ErrorDetails[] | 更具体的错误的可选数组。 |
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"
]
}
- 错误详情
包含错误信息。
名称 | 类型 | 描述 |
---|---|---|
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
,因为该错误可能已阻止构造此响应。
名称 | 类型 | 描述 |
---|---|---|
error | Error | 错误信息 |
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. 请求
- 请求参数
名称 | 位置 | 必填? | 描述 |
---|---|---|---|
id | 模板 | 是 | Webhook ID |
- 请求头
名称 | 必填? | 描述 |
---|---|---|
Authorization | 是 | 具有 webhooks:modify 作用域的 OAuth 访问令牌 |
Accept | 否 | 推荐设置为application/vnd.bentley.itwin-platform.v1+json |
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." } }
名称 | 描述 |
---|---|
retry-after | 请求数超过客户端订阅的速率限制。 |
4.3.4. 定义
- 激活webhook
Webhook 激活的其他属性。
名称 | 类型 | 描述 |
---|---|---|
expirationDateTime | 字符串 | Webhook 到期日期和时间。如果未提供,则默认为请求时间后 30 天。 |
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."
}
}
}
- 错误
包含错误信息和更具体的错误的可选数组。
名称 | 类型 | 描述 |
---|---|---|
code | 字符串 | 服务器定义的一组错误代码之一 |
message | 字符串 | 错误的人类可读表示形式。 |
details | ErrorDetails[] | 更具体的错误的可选数组。 |
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"
]
}
- 错误详情
包含错误信息。
名称 | 类型 | 描述 |
---|---|---|
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
,因为该错误可能已阻止构造此响应。
名称 | 类型 | 描述 |
---|---|---|
error | Error | 错误信息 |
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. 请求
- 请求参数
名称 | 位置 | 必填? | 描述 |
---|---|---|---|
id | 模板 | 是 | Webhook ID |
- 请求头
名称 | 必填? | 描述 |
---|---|---|
Authorization | 是 | 具有 webhooks:modify 作用域的 OAuth access token |
Accept | 否 | 推荐设置为application/vnd.bentley.itwin-platform.v1+json |
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." } }
名称 | 描述 |
---|---|
retry-after | 请求数超过客户端订阅的速率限制。 |
4.4.3. 定义
- 错误
包含错误信息和更具体的错误的可选数组。
名称 | 类型 | 描述 |
---|---|---|
code | 字符串 | 服务器定义的一组错误代码之一 |
message | 字符串 | 错误的人类可读表示形式。 |
details | ErrorDetails[] | 更具体的错误的可选数组。 |
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"
]
}
- 错误详情
包含错误信息。
名称 | 类型 | 描述 |
---|---|---|
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
,因为该错误可能已阻止构造此响应。
名称 | 类型 | 描述 |
---|---|---|
error | Error | 错误信息 |
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. 请求
- 请求头
名称 | 必填? | 描述 |
---|---|---|
Authorization | 是 | 具有 webhooks:read 作用域的 OAuth access token |
Accept | 否 | 推荐设置为application/vnd.bentley.itwin-platform.v1+json |
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." } }
名称 | 描述 |
---|---|
retry-after | 请求数超过客户端订阅的速率限制。 |
4.5.4. 定义
- Webhook
名称 | 类型 | 描述 |
---|---|---|
id | 字符串 | Webhook 的全局唯一标识符。 |
eventSource | 字符串 | Webhook 事件源名称 |
isActive | 布尔值 | 显示 Webhook 活动的指示器。如果为 true,则 Webhook 正在主动转发事件。如果为 false,则停止 Webhook 事件。 |
isValidated | 布尔值 | 指示是否验证了 Webhook 回调所有权的一个值。 |
callbackUrl | 字符串 | 将发送 Webhook 事件的 URL。 |
expirationDateTime | 字符串 | Webhook 到期日期和时间。如果未提供,则默认为请求时间后 30 天。 |
- 错误
包含错误信息和更具体的错误的可选数组。
名称 | 类型 | 描述 |
---|---|---|
code | 字符串 | 服务器定义的一组错误代码之一 |
message | 字符串 | 错误的人类可读表示形式。 |
details | ErrorDetails[] | 更具体的错误的可选数组。 |
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"
]
}
- 错误详情
包含错误信息。
名称 | 类型 | 描述 |
---|---|---|
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
,因为该错误可能已阻止构造此响应。
名称 | 类型 | 描述 |
---|---|---|
error | Error | 错误信息 |
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. 请求
- 请求参数
名称 | 位置 | 必填? | 描述 |
---|---|---|---|
id | 模板 | 是 | Webhook ID |
- 请求头
名称 | 必填? | 描述 |
---|---|---|
Authorization | 是 | 具有 webhooks:read 作用域的 OAuth access token |
Accept | 否 | 推荐设置为application/vnd.bentley.itwin-platform.v1+json |
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." } }
名称 | 描述 |
---|---|
retry-after | 请求数超过客户端订阅的速率限制。 |
4.6.4. 定义
Webhook
详细信息
名称 | 类型 | 描述 |
---|---|---|
id | 字符串 | Webhook 的全局唯一标识符 |
isActive | 布尔值 | 显示 Webhook 活动的指示器。如果为 true,则 Webhook 正在主动转发事件。如果为 false,则停止 Webhook 事件 |
isValidated | 布尔值 | 指示是否验证了 Webhook 回调所有权的一个值 |
callbackUrl | 字符串 | 将发送 Webhook 事件的 URL |
expirationDateTime | 字符串 | Webhook 到期日期和时间。如果未提供,则默认为请求时间后 30 天 |
validationState | 字符串 | 描述当前的 Webhook 回调验证状态 |
_links | object |
- 错误
包含错误信息和更具体的错误的可选数组。
名称 | 类型 | 描述 |
---|---|---|
code | 字符串 | 服务器定义的一组错误代码之一 |
message | 字符串 | 错误的人类可读表示形式。 |
details | ErrorDetails[] | 更具体的错误的可选数组。 |
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"
]
}
- 错误详情
包含错误信息。
名称 | 类型 | 描述 |
---|---|---|
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
,因为该错误可能已阻止构造此响应。
名称 | 类型 | 描述 |
---|---|---|
error | Error | 错误信息 |
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. 请求
- 请求参数
名称 | 位置 | 必填? | 描述 |
---|---|---|---|
id | query | 是 | Webhook ID |
key | query | 是 | 唯一的 Webhook 终结点确认密钥 |
- 请求头
名称 | 必填? | 描述 |
---|---|---|
Authorization | 是 | 具有 webhooks:modify 作用域的 OAuth access token |
Accept | 否 | 推荐设置为application/vnd.bentley.itwin-platform.v1+json |
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." } }
名称 | 描述 |
---|---|
retry-after | 请求数超过客户端订阅的速率限制。 |
4.7.4. 定义
Webhook
详细信息
名称 | 类型 | 描述 |
---|---|---|
id | 字符串 | Webhook 的全局唯一标识符 |
isActive | 布尔值 | 显示 Webhook 活动的指示器。如果为 true,则 Webhook 正在主动转发事件。如果为 false,则停止 Webhook 事件 |
isValidated | 布尔值 | 指示是否验证了 Webhook 回调所有权的一个值 |
callbackUrl | 字符串 | 将发送 Webhook 事件的 URL |
expirationDateTime | 字符串 | Webhook 到期日期和时间。如果未提供,则默认为请求时间后 30 天 |
validationState | 字符串 | 描述当前的 Webhook 回调验证状态 |
_links | object |
- 错误
包含错误信息和更具体的错误的可选数组。
名称 | 类型 | 描述 |
---|---|---|
code | 字符串 | 服务器定义的一组错误代码之一 |
message | 字符串 | 错误的人类可读表示形式。 |
details | ErrorDetails[] | 更具体的错误的可选数组。 |
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"
]
}
- 错误详情
包含错误信息。
名称 | 类型 | 描述 |
---|---|---|
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
,因为该错误可能已阻止构造此响应。
名称 | 类型 | 描述 |
---|---|---|
error | Error | 错误信息 |
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"
]
}