Webhooks
事件
所有可用的 Webhook 事件类型及其载荷结构。
事件信封
所有事件使用相同的顶层结构：
json
{
"event": "user.created",
"data": { ... },
"timestamp": "2026-01-15T10:30:00.000Z"
}用户事件
user.created当新用户首次注册或通过 API 创建时触发。
event.data
json
{
"event": "user.created",
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"displayName": "John Doe",
"emailVerified": false,
"isBanned": false,
"avatarUrl": null,
"publicMetadata": null,
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-15T10:30:00.000Z"
}
},
"timestamp": "2026-01-15T10:30:00.000Z"
}user.updated当用户资料或元数据被更新时触发。
event.data
json
{
"event": "user.updated",
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"displayName": "John Doe (Updated)",
"emailVerified": true,
"isBanned": false,
"avatarUrl": "https:0
10: { 11: "pro" },
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-16T09:00:00.000Z"
}
},
"timestamp": "2026-01-16T09:00:00.000Z"
}user.deleted当用户账户被永久删除时触发。data 字段包含删除前用户的快照。
event.data
json
{
"event": "user.deleted",
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"displayName": "John Doe",
"createdAt": "2026-01-15T10:30:00.000Z"
}
},
"timestamp": "2026-01-20T11:00:00.000Z"
}user.signin当用户通过邮箱/密码或 OAuth 成功登录时触发。
event.data
json
{
"event": "user.signin",
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"displayName": "John Doe",
"emailVerified": true,
"isBanned": false
}
},
"timestamp": "2026-01-15T10:30:00.000Z"
}user.signout当用户主动退出登录时触发。
event.data
json
{
"event": "user.signout",
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"displayName": "John Doe",
"emailVerified": true,
"isBanned": false
}
},
"timestamp": "2026-01-15T12:00:00.000Z"
}user.banned当管理员封禁用户时触发。所有活跃会话被撤销。
event.data
json
{
"event": "user.banned",
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"displayName": "John Doe",
"isBanned": true
}
},
"timestamp": "2026-01-15T10:30:00.000Z"
}user.unbanned当用户封禁被解除时触发。
event.data
json
{
"event": "user.unbanned",
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"displayName": "John Doe",
"isBanned": false
}
},
"timestamp": "2026-01-16T10:00:00.000Z"
}会话事件
session.created当新会话被创建时触发 — 登录或令牌刷新时。
event.data
json
{
"event": "session.created",
"data": {
"session": {
"id": "sess_abc123",
"userId": "usr_abc123",
"ipAddress": "203.0.113.1",
"userAgent": "Mozilla/5.0...",
"createdAt": "2026-01-15T10:30:00.000Z"
},
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"displayName": "John Doe"
}
},
"timestamp": "2026-01-15T10:30:00.000Z"
}session.revoked当会话被撤销时触发 — 退出登录或管理员强制撤销时。
event.data
json
{
"event": "session.revoked",
"data": {
"session": {
"id": "sess_abc123",
"userId": "usr_abc123",
"ipAddress": "203.0.113.1",
"userAgent": "Mozilla/5.0...",
"createdAt": "2026-01-15T10:30:00.000Z"
},
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"displayName": "John Doe"
}
},
"timestamp": "2026-01-15T11:00:00.000Z"
}操作与事件映射
下表显示哪些 SDK 操作和控制台操作会触发哪些事件。
| 操作 | 触发的事件 |
|---|---|
| SDK: signup() | user.created + session.created |
| SDK: signin() | user.signin + session.created |
| SDK: signout() | user.signout + session.revoked |
| SDK：OAuth 登录（新用户） | user.created + session.created |
| SDK：OAuth 登录（现有用户） | user.signin + session.created |
| SDK: refreshTokens() | session.revoked + session.created |
| 控制台：封禁用户 | user.banned |
| 控制台：解除封禁 | user.unbanned |
| 控制台：删除用户 | user.deleted |
| 控制台：更新元数据 | user.updated |
| 后端 API：创建用户 | user.created |
| 后端 API：更新用户 | user.updated |
| 后端 API：删除用户 | user.deleted |
| 后端 API：封禁用户 | user.banned |
| 后端 API：解除封禁 | user.unbanned |
| SDK: revokeSession() | session.revoked |
处理器示例
涵盖最常见用户同步场景的最小化事件处理器：
routes/webhooks.ts
const { event, data } = JSON.parse(req.body.toString());
switch (event) {
case "user.created":
await db.users.create({ authonId: data.user.id, email: data.user.email });
break;
case "user.updated":
await db.users.update({ authonId: data.user.id }, { name: data.user.displayName });
break;
case "user.deleted":
await db.users.delete({ authonId: data.user.id });
break;
case "user.banned":
await db.users.update({ authonId: data.user.id }, { suspended: true });
break;
case "user.unbanned":
await db.users.update({ authonId: data.user.id }, { suspended: false });
break;
case "session.created":
console.log(`${data.user.email} signed in from ${data.session.ipAddress}`);
break;
}