> ## 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: bank.link, 연결 및 데이터 이벤트

> Didit의 bank.link, bank.connection, bank.data, bank.sync webhook 이벤트가 언제 전송되는지, 어떤 데이터를 담는지, 일일 데이터 조회에 어떻게 활용하는지 설명합니다.

Didit는 링크가 종료되거나, 연결 상태가 변경되거나, 동의 기간이 곧 만료되거나, 동기화로 새 데이터가 저장될 때 은행 webhook을 보냅니다. 이 webhook은 다른 Didit webhook과 같은 엔벨로프, 서명, 재시도 방식을 사용하며, ID와 상태 값만 포함합니다. 내용을 읽으려면 해당 객체를 직접 조회해야 합니다.

> [!NOTE]
>
> 은행 webhook 이벤트는 프로덕션 애플리케이션과 샌드박스 애플리케이션 모두에 전송됩니다.
> 다른 이벤트와 마찬가지로 대상의 이벤트 필터에서 대상별로 이벤트를 선택합니다.
> 엔벨로프, 서명 헤더, 재시도에 대한 내용은 [Webhooks](https://docs.didit.me/ko/integration/webhooks.md)을 참조하세요.

## 이벤트

| 이벤트 | 발생 시점 | 필드 |
| - | - | - |
| `bank.link.completed` | 사용자가 은행을 연결했습니다. | `data.link_id`, `data.status`, `data.connection_id`, `data.check_id`, `data.error_code` (항상 `null`) |
| `bank.link.cancelled` | 사용자가 취소했습니다. | `data.link_id`, `data.status` |
| `bank.link.expired` | 완료되기 전에 링크가 만료되었습니다. | `data.link_id`, `data.status` |
| `bank.link.failed` | 링크가 오류와 함께 종료되었습니다. | `data.link_id`, `data.status`, `data.error_code` |
| `bank.connection.created` | 첫 동기화가 완료되어 계좌를 조회할 수 있습니다. | `connection_id`, `initial_status` |
| `bank.connection.history_complete` | 이유와 관계없이 과거 내역 가져오기가 종료되었습니다. | `connection_id`, `status` |
| `bank.connection.updated` | 상태, 동의 또는 동기화 상태가 변경되었습니다. | `connection_id`, `status`, `revocation_status` |
| `bank.connection.consent_expiring` | 동의 만료 14일, 7일, 1일 전입니다. | `connection_id`, `days_left`, `consent_expires_at`, `renew_by` |
| `bank.connection.renewal_required` | 동의가 만료되었거나 은행이 사용자에게 다시 로그인을 요청합니다. | `connection_id`, `status`, `reason`, `renew_by`, `renewable_until` |
| `bank.connection.renewed` | 갱신 링크가 완료되었습니다. | `connection_id`, `status`, `consent_version`, `link_id`, `consent_expires_at` |
| `bank.connection.revoked` | 접근 권한이 종료되었습니다. | `connection_id`, `status`, `ended_by`, `status_reason`, `ended_at`, `retain_until` |
| `bank.connection.deleted` | 연결과 해당 데이터가 삭제되었습니다. | `connection_id`, `status`, `erasure_status`, `reason`, `erased_at` |
| `bank.data.updated` | 동기화로 변경 사항이 저장되었습니다. | `connection_id`, `sync_id`, `trigger`, `accounts` (건수가 포함된 ID), `balances_changed` |
| `bank.sync.completed` | 모든 동기화가 완료되었습니다. | `connection_id`, `sync_id`, `trigger`, `outcome`, `changed` |
| `bank.sync.failed` | 동기화가 계속 실패하고 있습니다. | `connection_id`, `sync_id`, `error_code`, `failing_since` |
| `bank.sync.recovered` | 실패하던 동기화가 다시 정상 작동합니다. | `connection_id`, `sync_id` |

모든 이벤트에는 공통 필드인 `event_id`, `webhook_type`, `timestamp`, `created_at`, `application_id`, `environment`도 포함됩니다.
`bank.link.*` 이벤트의 필드는 `data` 아래에 있으며, 연결, 데이터, 동기화 이벤트의 필드는 최상위 레벨에 있습니다.
`ended_by` 값은 `end_user`, `bank`, `customer` 또는 `unknown`입니다.
각 이벤트의 정확한 스키마는 [API 레퍼런스](https://docs.didit.me/ko/standalone-apis/bank-data.md)에서 확인할 수 있습니다.

## 예시

```json theme={null}
{
  "event_id": "7c1e0a52-93d4-4a6b-8f21-0d5b9e3a64c7",
  "webhook_type": "bank.sync.completed",
  "timestamp": 1763804640,
  "created_at": 1763804640,
  "application_id": "b3e1f0a2-5d64-4c8e-9a17-2f6d0c8b7e41",
  "environment": "sandbox",
  "connection_id": "5e1d2a70-3b4c-4d5e-8f60-71829304a5b6",
  "sync_id": "c2b8d4f6-9a13-4e07-85bc-3d6e1f0a7b92",
  "trigger": "scheduled",
  "outcome": "succeeded",
  "changed": true
}
```

## 사용 방법

* **새 데이터.** `bank.data.updated`는 신호일 뿐이며, 데이터가 함께 전송되지는 않습니다. 저장해 둔 커서로 [변경 피드](https://docs.didit.me/ko/standalone-apis/bank-transactions-sync.md)를 호출하세요. 변경이 없었던 동기화까지 모두 확인하려는 경우에만 `bank.sync.completed`를 사용하세요.
* **온보딩.** 계좌를 읽기 전에 `bank.connection.created`를 기다리고, 전체 이력에 의존하기 전에 `bank.connection.history_complete`를 기다리세요.
* **동의.** `bank.connection.consent_expiring`을 받으면 사용자에게 동의 갱신을 요청하세요. `bank.connection.renewal_required`를 받으면 데이터는 여전히 읽을 수 있지만 더 이상 동기화되지 않습니다.
* **중단.** `bank.connection.revoked`를 받으면 해당 연결에 대한 자체 피드를 중단하고, 저장된 데이터를 [삭제](https://docs.didit.me/ko/standalone-apis/bank-connection-delete.md)할지 결정하세요.
* **중복.** 모든 이벤트를 멱등성 있게 처리하세요. 이벤트 ID를 기준으로 식별하고, 같은 이벤트가 간혹 두 번 도착할 수 있다고 가정하세요.
* **브라우저를 신뢰하지 마세요.** 페이지가 전송한 링크 ID가 아니라 `bank.link.completed` 또는 `GET /v3/bank/links/{id}/`로 링크를 확인하세요.

## Next steps

* [회계를 위한 지속적인 은행 거래 내역 피드](https://docs.didit.me/ko/use-cases/bank-data-for-accounting.md)
* [샌드박스](https://docs.didit.me/ko/core-technology/bank-verification/sandbox.md): Didit Test Bank에서 이 이벤트들이 발생합니다.


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