웹훅

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

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

등록 요청

contact@verchase.com으로 아래 템플릿을 채워 보내 주세요.

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

앱 이름:
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 웹훅과 같은 형식에 workspaceId가 더해져요. data는 v2 웹훅의 주문, 입금 페이로드와 같아요.

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

{
  "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"
  }
}

{
  "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`	앱이 토큰 폐기를 호출했어요.
`workspace_deleted`	고객이 워크스페이스를 삭제했어요.

서명과 재시도

헤더, 서명 검증, 재시도, 중복 처리는 v2 웹훅과 같아요. 서명은 등록할 때 받은 서명 시크릿으로 검증해요. 7번 모두 실패해도 메일은 보내지 않아요.