웹훅
이벤트
사용 가능한 모든 웹훅 이벤트 유형과 페이로드 구조.
이벤트 봉투
모든 이벤트는 동일한 최상위 구조를 사용합니다:
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 |
| Backend API: 사용자 생성 | user.created |
| Backend API: 사용자 수정 | user.updated |
| Backend API: 사용자 삭제 | user.deleted |
| Backend API: 사용자 차단 | user.banned |
| Backend 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;
}