---
title: 웹훅 개요
description: API 버전을 v1로 만든 웹훅이 보내는 이벤트 3종과 페이로드 형식, v2에서 달라진 전송 규칙이에요.
sidebar:
  label: 개요
  order: 1
---

v1 웹훅은 예전에 만든 웹훅 수신 서버가 그대로 동작하도록 남겨 둔 형식이에요. v2 전환 전에 만든 웹훅은 모두 v1로 옮겨졌어요. 새로 만든다면 이벤트 7종을 받는 [v2 웹훅](/api-reference/webhooks/overview)을 쓰세요.

## v1 웹훅 만들기

대시보드 [웹훅](https://paysync.kr/dashboard/webhooks)에서 **웹훅 추가**를 누르고 **API 버전**을 **v1**로 골라요. v1 웹훅은 아래 이벤트만 고를 수 있어요.

| 이벤트 | 전송 시점 |
| --- | --- |
| [`invoice.created`](/api-reference/v1/webhooks/invoice-created) | 주문이 만들어졌어요. |
| [`invoice.paid`](/api-reference/v1/webhooks/invoice-paid) | 주문이 결제 완료됐어요. |
| [`invoice.deleted`](/api-reference/v1/webhooks/invoice-deleted) | 주문이 취소됐어요. |

주문 만료, 주문 수정, 새 입금처럼 v2에만 있는 이벤트는 v1 웹훅으로 보내지 않아요.

## 페이로드

모든 이벤트는 `type`과 [v1 주문 객체](/api-reference/v1/invoices/get#주문-객체)를 담아요. `invoice.paid`에는 `trigger`가 더 붙어요.

```json
{
  "type": "invoice.paid",
  "invoice": { "id": "ivc_...", "...": "..." },
  "trigger": "AUTOMATIC_MATCHING"
}
```

`invoice` 안의 시각은 [v1 API](/api-reference/v1)와 같은 `2026-04-28T03:14:15.000+00:00` 형식이에요. v2 웹훅처럼 `id`, `timestamp`, `data`로 감싸지 않아요.

## 서명 검증

서명 방식은 v2 웹훅과 같아요. `webhook-id`, `webhook-timestamp`, `webhook-signature` 헤더로 [Standard Webhooks](https://www.standardwebhooks.com/) 서명을 검증하세요. 언어별 검증 코드는 [웹훅 개요의 서명 검증](/api-reference/webhooks/overview#서명-검증)에 있어요.

## v2에서 달라진 전송 규칙

| 항목 | 예전 | 지금 |
| --- | --- | --- |
| 성공 응답 | HTTP `200`만 | `200`부터 `299`까지 모든 `2xx` |
| 응답 대기 | 1분 | 10초 |
| 실패한 전송 | 다시 보내지 않음 | 30초, 1분, 2분, 4분, 8분, 16분 뒤에 다시 보냄 (최대 7번) |
| `Content-Type` 헤더 | 없을 수 있음 | `application/json` |
| `webhook-id` | 전송마다 새 값 | 같은 전송의 재시도에서는 같은 값, 수동 재전송에서는 새 값 |
| 카페24 주문 취소 | `invoice.deleted`를 보내지 않음 | `invoice.deleted`를 보냄 |

재시도가 생겨서 같은 이벤트를 여러 번 받을 수 있어요. 주문 ID와 이벤트 종류로 중복을 걸러 주세요. 7번 모두 실패하면 [이메일 알림](https://paysync.kr/account/notifications)에서 **웹훅 전송 실패**를 켠 멤버에게 메일을 보내요.

전송 기록 확인, 재전송, 재시도 멈추기, 서명 키 교체는 [웹훅 개요](/api-reference/webhooks/overview#7-실패-처리)를 참고하세요.