> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorylake.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 添加 Webhook

> 添加一个接收所选团队事件的接收地址

```
POST /openapi/memorylake/admin/v1/webhooks
```

添加一个接收所选团队事件的接收地址。响应中带有签名密钥——这是唯一一次显示。请求按 Standard Webhooks 方式签名（`webhook-id`、`webhook-timestamp`、`webhook-signature`）。接收地址必须以 https\:// 开头并解析到公网地址；每个团队最多 10 个 Webhook。

> [!NOTE]
>
> **所需权限：** `webhook:manage`

### 请求体

**url** `string` *required*

接收地址。必须以 https\:// 开头，且不能解析到内网、本机或保留地址。

**all\_events** `boolean`

发送全部事件类型，包括以后新增的类型

**description** `string`

说明，最多 100 个字符

**events** `array`

要发送的事件类型（见[列出事件类型](https://docs.memorylake.cn/features/memorylake/api-reference/webhooks/list-webhook-event-types.md)）。`all_events` 不为 true 时必填；不认识的类型会被忽略。

```bash cURL theme={null}
curl -X POST 'https://app.memorylake.cn/openapi/memorylake/admin/v1/webhooks' \
  -H 'Authorization: Bearer sk_xxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/url",
    "all_events": false,
    "description": "Example description",
    "events": [
      "example"
    ]
  }'
```

### 响应

**data** `object`

**Webhook With Secret 对象**

**secret** `string`

签名密钥（`whsec_…`）。只在本次响应中显示——请立即保存；丢失后只能更换。

**webhook** `object`

**Webhook 对象**

**all\_events** `boolean`

`true` = 发送全部事件类型，包括以后新增的类型；此时 `events` 是关闭该开关后要恢复的勾选

**created\_at** `integer`

添加该 Webhook 的时间，Unix 秒级时间戳

**description** `string`

说明；未填写时为空

**events** `array`

所选的事件类型（见[列出事件类型](https://docs.memorylake.cn/features/memorylake/api-reference/webhooks/list-webhook-event-types.md)）

**secret\_last4** `string`

当前签名密钥的末四位。完整密钥只在[添加 Webhook](https://docs.memorylake.cn/features/memorylake/api-reference/webhooks/create-webhook.md)与[更换签名密钥](https://docs.memorylake.cn/features/memorylake/api-reference/webhooks/rotate-webhook-secret.md)的响应中返回。

**status** `string`

`auto_disabled` = 连续 3 天投递全部失败后被自动停用；修好接收端后请重新启用。可选值：`enabled`、`disabled`、`auto_disabled`。

**url** `string`

事件发往的接收地址

**webhook\_id** `string`

Webhook 的标识

**created\_by\_member\_id** `string`

添加该 Webhook 的成员

**last\_delivery\_at** `integer`

最近一次尝试的时间，Unix 秒级时间戳；尚未发送过时不返回

**last\_delivery\_succeeded** `boolean`

最近一次投递是否成功

**previous\_secret\_expires\_at** `integer`

更换后旧密钥继续参与签名的截止时间，Unix 秒级时间戳；不在该期间时不返回

**secret\_rotated\_at** `integer`

签名密钥最近一次更换的时间，Unix 秒级时间戳；从未更换时不返回

```json Success (201) theme={null}
{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    "secret": "example",
    "webhook": {
      "all_events": false,
      "created_at": 1760000000,
      "description": "Example description",
      "events": [
        "example"
      ],
      "secret_last4": "example",
      "status": "enabled",
      "url": "https://example.com/url",
      "webhook_id": "b5f1a133e89a12f450352f1f50843c42",
      "created_by_member_id": "cb17cae3f79d7fd264472475d7d5d2fe",
      "last_delivery_at": 1760000000,
      "last_delivery_succeeded": false,
      "previous_secret_expires_at": 1760000000,
      "secret_rotated_at": 1760000000
    }
  }
}
```

### 错误

出错时返回 `success: false`、`message` 和 `error_code`。全部错误码见[错误码](https://docs.memorylake.cn/features/memorylake/api-reference/errors.md)。

| 状态码 | 含义 |
| - | - |
| `400` | 参数或请求体无效 |
| `401` | API Key 缺失、无效、已停用或已过期 |
| `403` | 该 Key 无权执行此操作 |
| `404` | 资源不存在 |
| `409` | 请求与当前状态冲突，例如重复或已达上限 |
| `422` | 请求体或参数未通过校验 |
| `429` | 请求过多，请按 `Retry-After` 等待后重试 |
| `500` | 服务端错误 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.