管理通知连接器

curl -X POST http://localhost:5080/api/v1/notify/connectors \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '{
    "name": "Operations webhook",
    "connector_type": "webhook",
    "config": {
      "url": "https://hooks.example.com/molesignal",
      "method": "post",
      "headers": { "Authorization": "Bearer <token>" },
      "timeout_secs": 5
    }
  }'

{
  "id": "3KEDlokKjNmves95sRzL8tXpflY",
  "organization_id": "<organization-id>",
  "name": "Operations webhook",
  "connector_type": "webhook",
  "config": {
    "url": "***",
    "method": "post",
    "headers": "***",
    "timeout_secs": 5
  },
  "capabilities": {
    "direct_user": true,
    "group": true,
    "rich_text": true,
    "interactive": false,
    "acknowledgement": false,
    "attachments": false
  },
  "enabled": true,
  "status": "unknown",
  "last_tested_at": null,
  "last_test_status": null,
  "last_test_error": null,
  "created_at": 1790000000000000,
  "updated_at": 1790000000000000
}

curl -X POST http://localhost:5080/api/v1/notify/connectors \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '{
    "name": "Operations webhook",
    "connector_type": "webhook",
    "config": {
      "url": "https://hooks.example.com/molesignal",
      "method": "post",
      "headers": { "Authorization": "Bearer <token>" },
      "timeout_secs": 5
    }
  }'

{
  "id": "3KEDlokKjNmves95sRzL8tXpflY",
  "organization_id": "<organization-id>",
  "name": "Operations webhook",
  "connector_type": "webhook",
  "config": {
    "url": "***",
    "method": "post",
    "headers": "***",
    "timeout_secs": 5
  },
  "capabilities": {
    "direct_user": true,
    "group": true,
    "rich_text": true,
    "interactive": false,
    "acknowledgement": false,
    "attachments": false
  },
  "enabled": true,
  "status": "unknown",
  "last_tested_at": null,
  "last_test_status": null,
  "last_test_error": null,
  "created_at": 1790000000000000,
  "updated_at": 1790000000000000
}

通知连接器为组织保存一个通知服务商的凭证与传输设置。列出和读取连接器需要 alerts.read。创建、更新、测试和删除连接器需要 alerts.manage。

操作	端点
列出连接器类型	`GET /api/v1/notify/connector-types`
列出连接器	`GET /api/v1/notify/connectors`
创建连接器	`POST /api/v1/notify/connectors`
读取连接器	`GET /api/v1/notify/connectors/{id}`
更新连接器	`PUT /api/v1/notify/connectors/{id}`
测试连接器	`POST /api/v1/notify/connectors/{id}/test`
删除连接器	`DELETE /api/v1/notify/connectors/{id}`

连接器类型

类型列表返回运行中后端注册的每种类型的 connector_type 与 capabilities。类型包括 email_smtp、lark_app、lark_webhook、slack_app、slack_webhook 和 webhook。

[
  {
    "connector_type": "slack_webhook",
    "capabilities": {
      "direct_user": false,
      "group": true,
      "rich_text": true,
      "interactive": false,
      "acknowledgement": false,
      "attachments": false
    }
  }
]

连接器的 config 对象取决于其类型。所有 timeout_secs 默认为 10，取值范围为 1 到 60。URL 必须是绝对的 http 或 https 地址。

`connector_type`	`config` 键
`email_smtp`	`host` 与 `from`（必填）、`port`（默认 `587`）、`username`、`password`、`tls`（`none`、默认的 `starttls` 或 `tls`）、`timeout_secs`
`slack_app`	`bot_token`、`client_id` 与 `client_secret`（至少填 Bot Token，或 Client ID 与 Client Secret，也可以三项都填）、`api_base_url`（默认 `https://slack.com/api`）、`timeout_secs`
`slack_webhook`	`webhook_url`（必填）、`timeout_secs`
`lark_app`	`app_id` 与 `app_secret`（必填）、`api_base_url`、`receive_id_type`（默认 `open_id`，另有 `user_id`、`union_id`、`email`、`chat_id`）、`timeout_secs`
`lark_webhook`	`webhook_url`（必填）、`secret`、`timeout_secs`
`webhook`	`url`（必填）、`method`（默认 `post`，另有 `put`、`patch`）、`headers`、`timeout_secs`

各服务商及其目标的说明参见通知渠道。

创建连接器

POST /api/v1/notify/connectors

字段	类型	必填	说明
`name`	string	是	在组织内唯一。
`connector_type`	string	是	上文的类型之一。创建后无法修改类型。`type` 可作为别名。
`config`	object	是	该类型的设置。
`enabled`	boolean	否	默认 `true`。

curl -X POST http://localhost:5080/api/v1/notify/connectors \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '{
    "name": "Operations webhook",
    "connector_type": "webhook",
    "config": {
      "url": "https://hooks.example.com/molesignal",
      "method": "post",
      "headers": { "Authorization": "Bearer <token>" },
      "timeout_secs": 5
    }
  }'

{
  "id": "3KEDlokKjNmves95sRzL8tXpflY",
  "organization_id": "<organization-id>",
  "name": "Operations webhook",
  "connector_type": "webhook",
  "config": {
    "url": "***",
    "method": "post",
    "headers": "***",
    "timeout_secs": 5
  },
  "capabilities": {
    "direct_user": true,
    "group": true,
    "rich_text": true,
    "interactive": false,
    "acknowledgement": false,
    "attachments": false
  },
  "enabled": true,
  "status": "unknown",
  "last_tested_at": null,
  "last_test_status": null,
  "last_test_error": null,
  "created_at": 1790000000000000,
  "updated_at": 1790000000000000
}

MoleSignal 对整个 config 做静态加密。响应会把每个保存凭证的键的值替换为 ***，这些键包括 url、webhook_url、headers，以及所有以 password、secret 或 token 结尾的键。host、from、timeout_secs 等其他键保持可读。 status 在首次测试之前为 unknown，之后为 connected 或 error。last_test_status 为 success 或 failed。状态为 error 的连接器会被路由跳过，直到之后的测试成功。

列出与读取连接器

GET /api/v1/notify/connectors
GET /api/v1/notify/connectors/{id}

列表返回上述格式的连接器数组。id 不存在时返回 404。

更新连接器

PUT /api/v1/notify/connectors/{id}

字段	类型	必填	说明
`name`	string	是	新名称。
`config`	object	否	新设置。省略则保留已保存的配置。
`enabled`	boolean	否	默认 `true`。省略该值会启用连接器。

对已掩码的键发送 *** 可保留已保存的密钥，发送新的明文值则替换它：

{
  "name": "Operations webhook",
  "config": {
    "url": "***",
    "method": "post",
    "headers": "***",
    "timeout_secs": 8
  },
  "enabled": true
}

测试连接器

POST /api/v1/notify/connectors/{id}/test

通过连接器发送一条消息。已停用的连接器无法运行测试。

字段	类型	必填	说明
`target_type`	string	是	`direct_user`、`fixed_address`、`fixed_group` 或 `webhook`。每种连接器类型只接受其中一部分，例如 `email_smtp` 接受 `direct_user` 与 `fixed_address`。
`target`	string	是	接收目标：地址、服务商标识符、群组或 URL，取决于 `target_type`。
`message`	object	否	`title`、`text`、`markdown` 与 `html`。默认使用通用的标题和正文。

{
  "sent": true,
  "tested_at_micros": 1790000000000000,
  "elapsed_ms": 3,
  "provider_message_id": "req-1",
  "error": null
}

投递失败时仍返回 200，sent 为 false，原因在 error 中，例如 unavailable: webhook request failed。测试还会更新连接器的 status、last_tested_at、last_test_status 与 last_test_error。

删除连接器

DELETE /api/v1/notify/connectors/{id}

删除成功时返回 204，没有响应体。用户端点、通知策略、兜底路由、定时日志巡检、状态页或 IM 里的 Mole Agent 仍引用该连接器时，调用返回 409，消息为

notify connector is referenced by user endpoints, policies, default routes, scheduled log inspections, status pages, or Mole Agent in IM

。请先迁移这些引用。

错误

状态码	原因
`400`	`config` 对该类型无效、类型不受支持（`unsupported connector type: pagerduty`）、目标与连接器不匹配，或连接器已停用。
`404`	连接器不存在。
`409`	组织内已有同名连接器，或删除时连接器仍被引用。
`422`	字段缺失或取值无效，例如未知的 `target_type`。响应为纯文本。

最后修改于 2026年10月21日

概览

身份验证

数据采集

查询

APM

用户体验

数据流

告警

关联与 Web

平台与管理

连接器类型

创建连接器

列出与读取连接器

更新连接器

测试连接器

删除连接器

错误

​连接器类型

​创建连接器

​列出与读取连接器

​更新连接器

​测试连接器

​删除连接器

​错误

连接器类型

创建连接器

列出与读取连接器

更新连接器

测试连接器

删除连接器

错误