---
title: 웹훅
description: 파트너 앱이 연결된 워크스페이스의 주문, 입금, 연결 이벤트를 웹훅으로 받는 방법이에요. 등록 요청 메일 템플릿과 이벤트, 페이로드 형식을 설명해요.
---

파트너 앱은 연결된 모든 워크스페이스의 이벤트를 앱에 등록한 웹훅 주소 하나로 받을 수 있어요. 웹훅 주소는 페이싱크가 등록해요.

## 등록 요청

[contact@verchase.com](mailto:contact@verchase.com)으로 아래 템플릿을 채워 보내 주세요.

```text
제목: [페이싱크 파트너 웹훅 등록 요청] {앱 이름}

앱 이름:
client_id: oap_
웹훅 URL: https://
받을 이벤트:
  - invoice.paid
  - app.disconnected
담당자 이름:
담당자 연락처:
요청 내용: 신규 등록 / URL 변경 / 이벤트 변경 / 시크릿 재발급 / 삭제
```

- 웹훅 URL은 인터넷에서 접근할 수 있는 주소여야 해요. 사설 IP나 `localhost`는 등록할 수 없어요.
- 등록이 끝나면 서명 시크릿을 한 번만 전달해요. `client_secret`과 마찬가지로 서버의 비밀 관리 도구에 보관하세요.
- `client_secret`과 액세스 토큰은 메일에 적지 마세요.

## 이벤트

| 이벤트 | 보내는 때 | 필요한 스코프 |
| --- | --- | --- |
| `invoice.created`, `invoice.updated`, `invoice.paid`, `invoice.expired`, `invoice.canceled`, `invoice.reopened` | 연결된 워크스페이스의 주문이 바뀌었어요. | `invoices:read` |
| `transaction.created` | 연결된 워크스페이스에 입금이 들어왔어요. | `transactions:read` |
| `app.connected` | 고객이 앱을 연결했거나 다시 연결했어요. | 없음 |
| `app.disconnected` | 연결이 끊겼어요. | 없음 |

주문과 입금 이벤트는 그 연결에서 고객이 허용한 스코프가 있을 때만 보내요.

## 페이로드

[v2 웹훅](/api-reference/webhooks/overview#페이로드)과 같은 형식에 `workspaceId`가 더해져요. `data`는 v2 웹훅의 주문, 입금 페이로드와 같아요.

```json invoice.paid
{
  "id": "evt_a1b2c3d4e5f6g7h8i9j0k1l2",
  "type": "invoice.paid",
  "timestamp": "2026-10-18T02:42:00Z",
  "workspaceId": "ws_a1b2c3d4e5f6g7h8i9j0k1l2",
  "data": {"id": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2", "status": "PAID"}
}
```

```json app.connected
{
  "id": "evt_b2c3d4e5f6g7h8i9j0k1l2m3",
  "type": "app.connected",
  "timestamp": "2026-10-18T02:40:00Z",
  "workspaceId": "ws_a1b2c3d4e5f6g7h8i9j0k1l2",
  "data": {
    "connectionId": "ocn_a1b2c3d4e5f6g7h8i9j0k1l2",
    "workspaceId": "ws_a1b2c3d4e5f6g7h8i9j0k1l2",
    "scopes": ["invoices:read", "invoices:write"],
    "connectedAt": "2026-10-18T02:40:00Z"
  }
}
```

```json app.disconnected
{
  "id": "evt_c3d4e5f6g7h8i9j0k1l2m3n4",
  "type": "app.disconnected",
  "timestamp": "2026-10-18T03:10:00Z",
  "workspaceId": "ws_a1b2c3d4e5f6g7h8i9j0k1l2",
  "data": {
    "connectionId": "ocn_a1b2c3d4e5f6g7h8i9j0k1l2",
    "workspaceId": "ws_a1b2c3d4e5f6g7h8i9j0k1l2",
    "reason": "customer",
    "disconnectedAt": "2026-10-18T03:10:00Z"
  }
}
```

`app.connected`의 `scopes`는 그 연결에서 지금 쓸 수 있는 스코프예요. `app.disconnected`의 `reason`은 아래 중 하나예요.

| reason | 뜻 |
| --- | --- |
| `customer` | 고객이 연결된 앱 화면에서 연결을 끊었어요. |
| `revoked` | 앱이 [토큰 폐기](/partners/oauth/revoke)를 호출했어요. |
| `workspace_deleted` | 고객이 워크스페이스를 삭제했어요. |

## 서명과 재시도

헤더, [서명 검증](/api-reference/webhooks/overview#서명-검증), [재시도](/api-reference/webhooks/overview#7-실패-처리), [중복 처리](/api-reference/webhooks/overview#8-멱등성)는 v2 웹훅과 같아요. 서명은 등록할 때 받은 서명 시크릿으로 검증해요. 7번 모두 실패해도 메일은 보내지 않아요.