Webhooks 模块

更新时间：2026-11-03

Webhook 接口

本文介绍 Webhook相关的 5 个接口。注册、更新和删除 webhook 事件订阅，并查看投递记录。

调用说明

接入地址：https://cloud.memory.bj.baidubce.com/api，下文路径直接拼接在该地址后。
请求头：Authorization: Bearer <token> 必填；有 JSON 请求体时需携带 Content-Type: application/json。
错误码、异步操作和 operationId 的说明见 API 简介。

接口列表

接口	方法	路径
注册 webhook	`POST`	`/v1/default/banks/{bank_id}/webhooks`
列出 webhook	`GET`	`/v1/default/banks/{bank_id}/webhooks`
删除 webhook	`DELETE`	`/v1/default/banks/{bank_id}/webhooks/{webhook_id}`
更新 webhook	`PATCH`	`/v1/default/banks/{bank_id}/webhooks/{webhook_id}`
列出 webhook delivery	`GET`	`/v1/default/banks/{bank_id}/webhooks/{webhook_id}/deliveries`

注册 webhook

POST /v1/default/banks/{bank_id}/webhooks

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。
`Content-Type`	header	`string`	是	固定`application/json`

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`url`	`string`	是	接收事件投递的 HTTP(S) endpoint URL。
`secret`	`string?`	否	HMAC-SHA256 签名密钥（可选）。
`event_types`	`array<string>`	否	要投递的事件类型列表。支持`retain.completed`、`consolidation.completed` 和 `memory_defense.triggered`；默认值：`["consolidation.completed"]`
`enabled`	`boolean`	否	此 webhook 是否启用；默认值：`true`
`http_config`	`WebhookHttpConfig`	否	HTTP 投递配置（method、timeout、headers、params）。

http_config · WebhookHttpConfig

数据结构 WebhookHttpConfig：

字段	类型	必填	说明
`method`	`string`	否	HTTP method：GET 或 POST；默认值：`"POST"`
`timeout_seconds`	`integer`	否	HTTP 请求超时时间，单位为秒；默认值：`30`
`headers`	`map<string, string>`	否	自定义 HTTP headers。
`params`	`map<string, string>`	否	自定义 HTTP query 参数。

请求示例

                JSON
                
            

                {
  "url": "string",
  "secret": "string",
  "event_types": [
    "consolidation.completed"
  ],
  "enabled": true,
  "http_config": {
    "method": "POST",
    "timeout_seconds": 30,
    "headers": {},
    "params": {}
  }
}
            

响应

状态码：201 — 成功响应
格式：application/json

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`bank_id`	`string?`	否	Bank 的唯一标识符。
`url`	`string`	是	Webhook 接收事件通知的 HTTP(S) endpoint URL。
`secret`	`string?`	否	签名密钥（响应中会脱敏）。
`event_types`	`array<string>`	是	订阅的事件类型列表。
`enabled`	`boolean`	是	是否启用。
`http_config`	`WebhookHttpConfig`	否	HTTP 配置。
`created_at`	`string?`	否	创建时间。
`updated_at`	`string?`	否	最后更新时间。

http_config · WebhookHttpConfig

数据结构 WebhookHttpConfig：

字段	类型	必填	说明
`method`	`string`	否	HTTP method：GET 或 POST；默认值：`"POST"`
`timeout_seconds`	`integer`	否	HTTP 请求超时时间，单位为秒；默认值：`30`
`headers`	`map<string, string>`	否	自定义 HTTP headers。
`params`	`map<string, string>`	否	自定义 HTTP query 参数。

响应示例

                JSON
                
            

                {
  "id": "string",
  "bank_id": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "enabled": false,
  "secret": "string",
  "http_config": {
    "method": "POST",
    "timeout_seconds": 30,
    "headers": {},
    "params": {}
  },
  "created_at": "string",
  "updated_at": "string"
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=create_webhook

列出 webhook

GET /v1/default/banks/{bank_id}/webhooks

列出 bank 已注册的所有 webhooks。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`items`	`array<WebhookResponse>`	是	结果项目列表。

items[] · WebhookResponse

数据结构 WebhookResponse：

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`bank_id`	`string?`	否	Bank 的唯一标识符。
`url`	`string`	是	Webhook 接收事件通知的 HTTP(S) endpoint URL。
`secret`	`string?`	否	签名密钥（响应中会脱敏）。
`event_types`	`array<string>`	是	订阅的事件类型列表。
`enabled`	`boolean`	是	是否启用。
`http_config`	`WebhookHttpConfig`	否	HTTP 配置。
`created_at`	`string?`	否	创建时间。
`updated_at`	`string?`	否	最后更新时间。

http_config · WebhookHttpConfig

数据结构 WebhookHttpConfig：

字段	类型	必填	说明
`method`	`string`	否	HTTP method：GET 或 POST；默认值：`"POST"`
`timeout_seconds`	`integer`	否	HTTP 请求超时时间，单位为秒；默认值：`30`
`headers`	`map<string, string>`	否	自定义 HTTP headers。
`params`	`map<string, string>`	否	自定义 HTTP query 参数。

响应示例

                JSON
                
            

                {
  "items": [
    {
      "id": "string",
      "bank_id": "string",
      "url": "string",
      "event_types": [
        "string"
      ],
      "enabled": false,
      "secret": "string",
      "http_config": {
        "method": "POST",
        "timeout_seconds": 30,
        "headers": {},
        "params": {}
      },
      "created_at": "string",
      "updated_at": "string"
    }
  ]
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=list_webhooks

删除 webhook

DELETE /v1/default/banks/{bank_id}/webhooks/{webhook_id}

删除已注册的 webhook。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`webhook_id`	path	`string`	是	Webhook 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`success`	`boolean`	是	操作是否成功。
`message`	`string?`	否	操作结果消息。
`deleted_count`	`integer?`	否	已删除数量。

响应示例

                JSON
                
            

                {
  "deleted_count": 10,
  "message": "Deleted successfully",
  "success": true
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=delete_webhook

更新 webhook

PATCH /v1/default/banks/{bank_id}/webhooks/{webhook_id}

更新已注册 webhook 的一个或多个字段；只修改请求中提供的字段。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`webhook_id`	path	`string`	是	Webhook 的唯一 ID。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。
`Content-Type`	header	`string`	是	固定`application/json`

请求体

格式：application/json
必填：是

字段	类型	必填	说明
`url`	`string?`	否	HTTP(S) endpoint 的 URL。
`secret`	`string?`	否	HMAC-SHA256 签名密钥。省略则保留现有密钥；传入 null 则清除。
`event_types`	`array<string>?`	否	事件类型列表。
`enabled`	`boolean?`	否	此 webhook 是否启用。
`http_config`	`WebhookHttpConfig?`	否	HTTP 投递配置。

http_config · WebhookHttpConfig

数据结构 WebhookHttpConfig：

字段	类型	必填	说明
`method`	`string`	否	HTTP method：GET 或 POST；默认值：`"POST"`
`timeout_seconds`	`integer`	否	HTTP 请求超时时间，单位为秒；默认值：`30`
`headers`	`map<string, string>`	否	自定义 HTTP headers。
`params`	`map<string, string>`	否	自定义 HTTP query 参数。

请求示例

                JSON
                
            

                {
  "url": "string",
  "secret": "string",
  "event_types": [
    "string"
  ],
  "enabled": false,
  "http_config": {
    "method": "POST",
    "timeout_seconds": 30,
    "headers": {},
    "params": {}
  }
}
            

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`bank_id`	`string?`	否	Bank 的唯一标识符。
`url`	`string`	是	Webhook 接收事件通知的 HTTP(S) endpoint URL。
`secret`	`string?`	否	签名密钥（响应中会脱敏）。
`event_types`	`array<string>`	是	订阅的事件类型列表。
`enabled`	`boolean`	是	是否启用。
`http_config`	`WebhookHttpConfig`	否	HTTP 配置。
`created_at`	`string?`	否	创建时间。
`updated_at`	`string?`	否	最后更新时间。

http_config · WebhookHttpConfig

数据结构 WebhookHttpConfig：

字段	类型	必填	说明
`method`	`string`	否	HTTP method：GET 或 POST；默认值：`"POST"`
`timeout_seconds`	`integer`	否	HTTP 请求超时时间，单位为秒；默认值：`30`
`headers`	`map<string, string>`	否	自定义 HTTP headers。
`params`	`map<string, string>`	否	自定义 HTTP query 参数。

响应示例

                JSON
                
            

                {
  "id": "string",
  "bank_id": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "enabled": false,
  "secret": "string",
  "http_config": {
    "method": "POST",
    "timeout_seconds": 30,
    "headers": {},
    "params": {}
  },
  "created_at": "string",
  "updated_at": "string"
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=update_webhook

列出 webhook delivery

GET /v1/default/banks/{bank_id}/webhooks/{webhook_id}/deliveries

查看 webhook 的 delivery 历史（便于调试）。

参数

名称	In	类型	必填	说明
`bank_id`	path	`string`	是	Bank 的唯一标识符。
`webhook_id`	path	`string`	是	Webhook 的唯一 ID。
`limit`	query	`integer`	否	最多返回的 delivery 数量；默认值：`50`；最大值：`200`
`cursor`	query	`string?`	否	分页 cursor，取上一页最后一项的 created_at。

请求头

名称	In	类型	必填	说明
`Authorization`	header	`string`	是	Bearer token。

响应

状态码：200 — 成功响应
格式：application/json

字段	类型	必填	说明
`items`	`array<WebhookDeliveryResponse>`	是	结果项目列表。
`next_cursor`	`string?`	否	下一页游标；没有下一页时为空。

items[] · WebhookDeliveryResponse

数据结构 WebhookDeliveryResponse：

字段	类型	必填	说明
`id`	`string`	是	资源的唯一标识符。
`webhook_id`	`string?`	否	Webhook 的唯一标识符。
`url`	`string`	是	Webhook 接收事件通知的 HTTP(S) endpoint URL。
`event_type`	`string`	是	事件类型。
`status`	`string`	是	当前处理状态；异步操作通常为 pending、processing、completed、failed 或 cancelled。
`attempts`	`integer`	是	投递尝试次数。
`next_retry_at`	`string?`	否	下次重试时间。
`last_error`	`string?`	否	最近一次错误。
`last_response_status`	`integer?`	否	最近一次响应状态码。
`last_response_body`	`string?`	否	最近一次响应正文。
`last_attempt_at`	`string?`	否	最近一次尝试时间。
`created_at`	`string?`	否	创建时间。
`updated_at`	`string?`	否	最后更新时间。

响应示例

                JSON
                
            

                {
  "items": [
    {
      "id": "string",
      "webhook_id": "string",
      "url": "string",
      "event_type": "string",
      "status": "string",
      "attempts": 0,
      "next_retry_at": "string",
      "last_error": "string",
      "last_response_status": 0,
      "last_response_body": "string",
      "last_attempt_at": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "next_cursor": "string"
}
            

响应

状态码：422 — 校验错误
格式：application/json

字段	类型	必填	说明
`detail`	`array<ValidationError>`	否	详细信息或校验错误列表。

detail[] · ValidationError

数据结构 ValidationError：

字段	类型	必填	说明
`loc`	`array<string \\| integer>`	是	发生校验错误的位置路径；数组元素可以是字段名或索引。
`msg`	`string`	是	错误消息或状态消息。
`type`	`string`	是	对象或错误的类型。
`input`	`any`	否	触发校验的原始输入值。
`ctx`	`Context`	否	错误上下文信息。

响应示例

                JSON
                
            

                {
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
            

operationId=list_webhook_deliveries

评价此篇文章

有帮助没帮助

Operations 模块

上下文数据服务

Webhooks 模块

Webhook 接口

调用说明

接口列表

注册 webhook

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

列出 webhook

参数

请求头

响应

响应示例

响应

响应示例

删除 webhook

参数

请求头

响应

响应示例

响应

响应示例

更新 webhook

参数

请求头

请求体

请求示例

响应

响应示例

响应

响应示例

列出 webhook delivery

参数

请求头

响应

响应示例

响应

响应示例