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

# 인증 이벤트 및 webhook

> Didit에서 로그인 활동이 콘솔에 전달되는 방식을 설명합니다. 사용자 로그인 요약과 타임라인, 사기 보기, 이벤트 규칙, auth.* webhook을 다룹니다.

> [!WARNING]
>
> 인증 기능은 새로 추가되었습니다. Didit은 귀사의 애플리케이션에 대해 이벤트 전송을 켭니다. 사용자를 로그아웃시키거나 차단하는 규칙 작업은 아직 활성화되지 않았습니다. 이러한 작업을 사용하는 규칙은 작업을 기록만 하고 적용하지는 않습니다.

Didit Authentication은 자체 활동을 Didit에 자동으로 전송합니다. 로그인 이벤트를 직접 제출할 필요가 없습니다. 각 이벤트는 동일한 `vendor_data`를 가진 사용자에게 기록되며, 해당 사용자의 인증 및 거래와 함께 표시됩니다.

같은 로그인에 대해 귀사의 `auth.login` 이벤트를 [`/v3/events/`](https://docs.didit.me/ko/transaction-monitoring/events)에 별도로 전송하지 마십시오. 이벤트가 두 번 저장되며, 사용자의 로그인 요약이 업데이트되지 않고 `auth.*` webhook도 전송되지 않습니다.

## 전송되는 항목

| 로그인 활동 | 저장 형식 | 웹훅 |
| - | - | - |
| 회원가입 | `auth.signup` | `auth.signup` |
| 로그인 | `auth.login` | `auth.login` |
| 로그인 실패 | `auth.login_failed` | `auth.login_failed` |
| 로그아웃 또는 세션 취소 | `auth.logout` | 없음 |
| 비밀번호 찾기 | `auth.password_forgot` | `auth.password_reset_requested` |
| 비밀번호 재설정 | `auth.password_reset` | `auth.password_reset_completed` |
| 비밀번호 변경 | `security.password_changed` | 없음 |
| 인증 수단 추가 또는 변경 | `security.mfa_changed` | `auth.mfa_changed` |
| 새 기기에서 로그인 | `security.device_changed` | `auth.new_device` |
| 계정 잠금 또는 차단 | `security.account_locked` | `auth.account_locked` |
| 에이전트 접근 승인 또는 철회 | `security.agent_access_approved`, `security.agent_access_revoked` | 없음 |

[봇 보호](https://docs.didit.me/ko/authentication/bot-protection.md) 결정(`attempt_challenged`, `attempt_blocked` 등)도 `auth.*` 이벤트로 저장되어 타임라인에 표시됩니다.

새 기기란 사용자가 이전에 로그인한 적이 없는 기기 ID와 지문 중 어느 것과도 일치하지 않는 기기를 의미합니다.

각 이벤트에는 다음 정보가 포함됩니다.

* 로그인 `method`(예: `password` 또는 `passkey`)와 실패 및 잠금에 대한 `reason`,
* IP 주소와 기기 정보: 영구 기기 ID, 지문, 사용자 에이전트와 클라이언트가 전송한 경우의 봇 점수,
* 세션 ID.

알 수 없거나 확인되지 않은 식별자에 대한 로그인 실패에는 `vendor_data`가 없습니다. Didit은 식별자 자체를 받지 않고 식별자의 키 기반 해시만 받습니다. 이러한 시도는 어떤 사용자에게도 연결되지 않지만, 아래의 사기 탐지 보기에서는 계정별로 계속 집계됩니다.

## 확인 위치

### 사용자 프로필

각 사용자에게는 로그인 요약이 제공되며, 이는 **사용자** 목록과 프로필에 표시되고 [`/v3/users/`](https://docs.didit.me/ko/management-api/users/list)에서 `authentication`으로 반환됩니다.

```json theme={null}
{
  "authentication": {
    "status": "ACTIVE",
    "methods": ["password", "passkey"],
    "mfa_enabled": true,
    "last_sign_in_at": "2026-10-14T09:12:44Z"
  }
}
```

* `status`는 `ACTIVE`, `LOCKED`(보안 정책에 의해 잠금) 또는 `BLOCKED`(귀사의 팀에 의해 차단) 중 하나입니다.
* 로그인 신원이 없는 사용자의 경우 `authentication`은 `null`입니다.
* **사용자** 목록은 로그인 상태, 로그인 방식("없음" 포함), MFA로 필터링할 수 있습니다.

### 이벤트 및 타임라인

로그인 이벤트는 콘솔의 **이벤트** 페이지와 각 사용자의 **이벤트** 탭에 표시됩니다. 이를 조회하려면 `list:transactions` 또는 `read:authentication` 권한이 필요합니다. 로그인 이벤트를 열면 기기 및 네트워크 정보, 보호 사유(예: `bots`, `stuffing`, `brute`, `vpn`, `travel`, `attack_mode`), 그리고 일치한 규칙이 표시됩니다.

### 사기 탐지 보기

**이벤트** 페이지에는 로그인 정보와 사용자의 다른 활동을 결합한 기본 제공 보기가 있습니다.

| 보기 | 찾아내는 항목 |
| - | - |
| 한 기기, 여러 사용자 | 7일 이내에 하나의 기기 지문을 3명 이상의 사용자가 사용한 경우 |
| 로그인 실패 급증 | 하나의 공인 IP에서 3개 이상의 계정에 대해 10회 이상 로그인이 실패한 경우(기본값 24시간), 가장 활발했던 30분 구간 포함 |
| 새 기기 후 지급 | 90일 동안 보이지 않던 기기에서 로그인한 후 15분 이내에 출금 또는 외부로 전송되는 거래가 발생한 경우 |
| 비밀번호 변경 후 거래 | 비밀번호 변경 후 30분 이내에 외부로 전송되는 거래가 발생한 경우 |
| 하나의 IP에서 많은 세션 | 48시간 동안 3명 이상의 사용자에 대해 3개 이상의 인증 세션이 생성된 경우 |

보기는 최대 31일 전까지의 데이터를 조회합니다.

## 이벤트 규칙

로그인 이벤트는 귀사의 다른 이벤트와 동일한 [이벤트 규칙](https://docs.didit.me/ko/transaction-monitoring/event-rules.md)을 거칩니다. **인증 사기** 번들에는 네 가지 프리셋이 있습니다.

| 프리셋 | 일치 조건 | 작업 |
| - | - | - |
| 계정 탈취 | 로그인 실패 3회 이상 후 비밀번호 또는 MFA 변경이 발생하고, 1시간 이내에 새 기기가 감지된 경우 | 거부(점수 90), 태그 지정, 로그아웃, 차단 |
| 자격 증명 대입 공격 | 하나의 IP에서 3개 이상의 계정에 대해 1시간 이내에 10회 이상 실패한 뒤 로그인이 성공한 경우 | 검토(점수 60), 태그 지정, 로그아웃 |
| 새 기기 후 지급 | 새 기기 감지 후 15분 이내에 출금이 발생한 경우 | 검토(점수 60), 태그 지정, 로그아웃 |
| 불가능한 이동 | 로그인 간 거리가 500km를 초과하고 속도가 시속 1,000km를 초과한 경우 | 검토(점수 50), 태그 지정, 로그아웃 |

자체 규칙에 유용한 필드는 `event.category`, `event.action_type`, `event.payload.method`, `event.payload.reason`, `event.security.changed_field`, `event.device.fingerprint`, `event.device.persistent_device_id`, `event.device.bot_score`, `event.ip.is_vpn_or_tor`, `event.ip.is_data_center`, `event.ip.country`, `event.ip.travel_distance_km`, `event.ip.travel_speed_kmh`입니다.

이벤트 규칙에서 로그인 이벤트에만 적용되는 작업은 두 가지입니다: **사용자의 모든 세션에서 로그아웃** 및 **사용자의 로그인 차단**. 이 작업들은 아직 활성화되지 않았습니다. 활성화되기 전까지 규칙은 이 작업을 상태 `DISABLED`로 기록하며 적용하지 않습니다. 그 밖의 작업(점수, 상태, 태그, 메모, 목록 및 케이스)은 평소와 같이 작동합니다.

## webhook

필요한 `auth.*` 유형에 대해 [webhook 대상](https://docs.didit.me/ko/integration/webhooks.md)을 구독하십시오. 구독한 대상만 해당 이벤트를 받습니다. 콘솔에서 **Try Webhook**을 사용하면 각 유형의 샘플을 보낼 수 있습니다.

```json auth.new_device theme={null}
{
  "webhook_type": "auth.new_device",
  "event_id": "0b6f2a71-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "timestamp": 1760433164,
  "created_at": 1760433164,
  "vendor_user_id": "8f0c3a52-4b7e-4a51-9a56-1f2d3c4b5a69",
  "vendor_data": "user-1234",
  "auth_event": {
    "event_id": "auth:3d0f1c2e-7a8b-4c5d-9e0f-1a2b3c4d5e6f",
    "event_uuid": "5b6c7d8e-9f01-4a2b-8c3d-4e5f60718293",
    "type": "security.device_changed",
    "method": "passkey",
    "reason": null,
    "occurred_at": "2026-10-14T09:12:44+00:00",
    "ip_address": "203.0.113.10",
    "device": {
      "fingerprint": "fp_7f3a",
      "label": "Chrome on Android",
      "persistent_device_id": "dev_4c21"
    }
  },
  "authentication": {
    "status": "ACTIVE",
    "methods": ["passkey"],
    "mfa_enabled": true,
    "last_sign_in_at": "2026-10-14T09:12:44Z"
  }
}
```

* `auth_event.event_id`, 즉 로그인 이벤트 자체의 ID로 중복을 제거하십시오. 이 값은 해당 이벤트의 모든 전송에서 동일하게 유지됩니다. `auth_event.event_uuid`는 `GET /v3/events/{event_uuid}/`에서 저장된 이벤트를 다시 조회하는 데 사용됩니다.
* 알려진 사용자를 지정하지 않은 시도의 경우 `vendor_data`, `vendor_user_id` 및 `authentication`은 `null`입니다.
* 다른 모든 Didit webhook과 동일하게 서명을 검증하십시오([webhook](https://docs.didit.me/ko/integration/webhooks.md) 참조).

## 결제

인증 이벤트는 이벤트별로 과금되지 않습니다. 인증은 월간 활성 사용자 수를 기준으로 과금됩니다.

## 애플리케이션이 소유하는 이벤트

프로필 변경이나 지급 요청처럼 고객사 제품 내에서 발생하는 작업은 서버에서 직접 이벤트를 제출하거나(`x-api-key`와 함께 `POST /v3/events/` 호출), 범위가 지정된 모니터링 토큰을 사용해 기기에서 제출할 수 있습니다. [이벤트](https://docs.didit.me/ko/transaction-monitoring/events.md) 및 [SDK 이벤트 제출](https://docs.didit.me/ko/transaction-monitoring/sdk-event-submission.md)을 참조하십시오. 해당 사용자의 액세스 토큰에 있는 `vendor_data`를 사용합니다.


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