7.5 · Webhooks 与事件（Webhooks and Events）

长期记忆与上下文管理 · 聚焦本章的模块关系、源码依据与实现要点。

项目Mem0 章节7.5 状态全文译文模块测试、发布与运维、界面与交互、系统架构、检索、召回与索引

项目要点页2.5 参考项目项目章节目录Mem0 DeepWiki 原始章节Webhooks and Events 上一章7.4 下一章7.6

源码线索

docs/api-reference/entities/delete-user.mdx
docs/api-reference/entities/get-users.mdx
docs/api-reference/events/get-event.mdx
docs/api-reference/events/get-events.mdx
docs/openapi.json
docs/platform/quickstart.mdx
mem0-ts/package.json
mem0-ts/src/client/index.ts
mem0-ts/src/client/mem0.ts
mem0-ts/src/client/mem0.types.ts

模块标签

测试、发布与运维
界面与交互
系统架构
检索、召回与索引
接口与服务契约

章节正文

Webhooks 与事件

原始 DeepWiki 页面https://deepwiki.com/mem0ai/mem0/7.5-webhooks-and-events

Webhooks 与事件

概述

Mem0 平台提供了两个互补的系统，用于监控和响应记忆操作：

Webhook —— 当指定事件发生时，通过 HTTP 回调将通知推送到您的应用程序。
事件 —— 所有记忆操作的可查询日志，包含状态追踪和性能指标。

这两个系统都是项目作用域的：Webhook 按项目配置，仅接收来自该项目的事件；事件查询则按项目上下文进行过滤。

主要特性：

异步处理：记忆操作在后台运行（v3 API），事件追踪其生命周期 docs/openapi.json:75-85。
有状态追踪：事件通过 PENDING、RUNNING、FAILED 和 SUCCEEDED 状态维护状态 docs/openapi.json:399-409。
实时通知：Webhook 在几秒内通过 HTTP POST 传递事件通知。
项目隔离：所有 Webhook 和事件数据都遵循组织/项目边界 mem0/client/main.py:776-781。

实现方式：

通过 MemoryClient 方法管理 Webhook：create_webhook()、get_webhooks()、update_webhook()、delete_webhook() mem0/client/main.py:773-835。
通过 REST 端点查询事件：GET /v1/events/ 和 GET /v1/event/{event_id}/ docs/openapi.json:357-568。

来源：mem0/client/main.py:773-835、docs/openapi.json:357-568、docs/openapi.json:75-85

系统架构

Webhook 注册与事件流

标题：Webhook 注册与事件流

Mem0 · 系统架构 · 图 1

该图展示了三个主要流程：

Webhook 配置：应用程序调用 client.create_webhook()，该方法发送 POST /api/v1/webhooks/ 以注册具有特定 event_types 的 Webhook 端点 mem0/client/main.py:791-809。
记忆操作：当调用 client.add() 时，会触发 POST /v3/memories/add/，该操作创建一个状态为 status: PENDING 的事件记录，并返回一个 event_id docs/openapi.json:75-85。
事件处理与通知：事件在状态间转换，完成后，Webhook 分发器根据配置的 event_types 进行过滤，并向匹配的 Webhook URL 发送 POST 请求。

来源：mem0/client/main.py:164-186、mem0/client/main.py:791-809、docs/openapi.json:357-461、docs/openapi.json:75-85

事件处理架构

标题：事件处理架构

Mem0 · 系统架构 · 图 2

每个记忆操作都会创建一个包含全面追踪数据的事件记录。在 TypeScript SDK 中，WebhookEvent 枚举定义了这些触发器 mem0-ts/src/client/mem0.types.ts:170-175。

字段	类型	描述
`id`	UUID	唯一事件标识符 `docs/openapi.json:391`
`event_type`	string	操作类型（ADD、UPDATE、DELETE、CATEGORIZE）`docs/openapi.json:397`
`status`	enum	处理状态（PENDING、RUNNING、FAILED、SUCCEEDED）`docs/openapi.json:399`
`payload`	object	触发事件的原始请求数据 `docs/openapi.json:411`
`metadata`	object	额外上下文（user_id、agent_id 等）`docs/openapi.json:423`
`results`	array	操作结果（创建/更新/删除的记忆）`docs/openapi.json:427`
`created_at`	datetime	事件创建时间戳（ISO 8601）`docs/openapi.json:445`
`latency`	number	处理时长（毫秒）`docs/openapi.json:446`

来源：docs/openapi.json:387-447、mem0/client/main.py:791-809、mem0-ts/src/client/mem0.types.ts:170-175

事件类型与生命周期

支持的事件类型

平台支持以下事件类型，这些类型在 SDK 中定义：

事件类型（代码）	枚举名称	描述
`memory_add`	`MEMORY_ADDED`	通过 `client.add()` 创建记忆 `mem0-ts/src/client/mem0.types.ts:171`
`memory_update`	`MEMORY_UPDATED`	通过 `client.update()` 修改记忆 `mem0-ts/src/client/mem0.types.ts:172`
`memory_delete`	`MEMORY_DELETED`	通过 `client.delete()` 删除记忆 `mem0-ts/src/client/mem0.types.ts:173`
`memory_categorize`	`MEMORY_CATEGORIZED`	异步分类过程 `mem0-ts/src/client/mem0.types.ts:174`

来源：mem0-ts/src/client/mem0.types.ts:170-175、docs/openapi.json:397-409

事件生命周期状态

事件通过一个定义好的生命周期进行状态转换。事件记录中的 status 字段遵循以下流程 docs/openapi.json:399-409：

PENDING：事件已创建并排队等待处理。
RUNNING：处理已开始（例如，大语言模型（LLM）事实提取）。
SUCCEEDED：操作成功完成。results 数组填充了记忆对象 docs/openapi.json:427-444。
FAILED：操作遇到错误。

延迟追踪： latency 字段以毫秒为单位提供操作性能指标，测量从开始到完成的时间 docs/openapi.json:446-447。

来源：docs/openapi.json:399-447、docs/openapi.json:489-545

Webhook 管理

创建 Webhook

Webhook 通过 MemoryClient.create_webhook() 方法创建。每个 Webhook 都限定在特定的项目和组织范围内 mem0/client/main.py:791-809。

Python 示例：

webhook = client.create_webhook(
    url="https://your-app.com/webhook",
    name="Memory Logger",
    event_types=["memory_add", "memory_categorize"]
)

TypeScript 示例：

const webhook = await client.createWebhook({
  name: "My Webhook",
  url: "https://example.com/webhook",
  eventTypes: [WebhookEvent.MEMORY_ADDED]
});

创建的载荷由 WebhookCreatePayload 接口定义 mem0-ts/src/client/mem0.types.ts:188-192。

来源：mem0/client/main.py:791-809、mem0-ts/src/client/mem0.types.ts:188-192

检索与更新 Webhook

操作	Python 方法	TypeScript 方法	API 端点
列出所有	`get_webhooks()`	`getWebhooks()`	`GET /v1/webhooks/` `mem0/client/main.py:773-789`
更新	`update_webhook()`	`updateWebhook()`	`PUT /v1/webhooks/{id}/` `mem0/client/main.py:811-825`
删除	`delete_webhook()`	`deleteWebhook()`	`DELETE /v1/webhooks/{id}/` `mem0/client/main.py:827-835`

更新载荷：使用 WebhookUpdatePayload，允许修改 name、url 和 eventTypes mem0-ts/src/client/mem0.types.ts:194-199。

来源：mem0/client/main.py:773-835、mem0-ts/src/client/mem0.types.ts:194-199

事件查询与监控

列出最近事件

检索当前组织和项目的事件，以监控系统健康或审计变更 docs/api-reference/events/get-events.mdx:1-13。

API 端点： GET /v1/events/ docs/openapi.json:357

响应字段：

字段	类型	描述
`count`	integer	事件总数 `docs/openapi.json:374`
`results`	array	事件对象列表，包含 `status`、`latency` 和 `payload` `docs/openapi.json:387-447`

使用场景：

仪表盘：汇总一段时间内的操作 docs/api-reference/events/get-events.mdx:11。
告警：轮询 FAILED 事件以触发恢复工作流 docs/api-reference/events/get-events.mdx:12。
审计：存储载荷以用于合规日志 docs/api-reference/events/get-events.mdx:13。

来源：docs/openapi.json:357-461、docs/api-reference/events/get-events.mdx:1-13

检索特定事件

通过事件 ID 查询单个事件，以获取完整的处理详情，包括大语言模型（LLM）提取结果 docs/api-reference/events/get-event.mdx:1-5。

API 端点： GET /v1/event/{event_id}/ docs/openapi.json:463

来源：docs/openapi.json:463-567、docs/api-reference/events/get-event.mdx:1-5

Webhook 载荷格式

当操作完成时，平台会向您的 URL 发送 POST 请求。

记忆操作载荷

对于 memory_add、memory_update 和 memory_delete，载荷包含生成的记忆状态。

{
  "event_details": {
    "id": "mem_uuid",
    "data": {
      "memory": "提取的事实文本"
    },
    "event": "ADD"
  }
}

Webhook 安全与最佳实践

HTTPS 强制：Webhook 端点仅接受 https:// URL。
异步处理：Webhook 处理器应立即（10 秒内）返回 2xx 状态码，并在后台队列中处理载荷 mem0/client/main.py:791-809。
幂等性：使用载荷中的 id 字段检测并忽略重复通知。
校验：如果您的端点受保护，请使用 Authorization 请求头校验请求。

来源：mem0/client/main.py:791-809、docs/openapi.json:357-567