웹훅 개요
API 버전을 v1로 만든 웹훅이 보내는 이벤트 3종과 페이로드 형식, v2에서 달라진 전송 규칙이에요.
v1 웹훅은 예전에 만든 웹훅 수신 서버가 그대로 동작하도록 남겨 둔 형식이에요. v2 전환 전에 만든 웹훅은 모두 v1로 옮겨졌어요. 새로 만든다면 이벤트 7종을 받는 v2 웹훅을 쓰세요.
v1 웹훅 만들기
대시보드 웹훅에서 웹훅 추가를 누르고 API 버전을 v1로 골라요. v1 웹훅은 아래 이벤트만 고를 수 있어요.
| 이벤트 | 전송 시점 |
|---|---|
invoice.created |
주문이 만들어졌어요. |
invoice.paid |
주문이 결제 완료됐어요. |
invoice.deleted |
주문이 취소됐어요. |
주문 만료, 주문 수정, 새 입금처럼 v2에만 있는 이벤트는 v1 웹훅으로 보내지 않아요.
페이로드
모든 이벤트는 type과 v1 주문 객체를 담아요. invoice.paid에는 trigger가 더 붙어요.
{
"type": "invoice.paid",
"invoice": { "id": "ivc_...", "...": "..." },
"trigger": "AUTOMATIC_MATCHING"
}invoice 안의 시각은 v1 API와 같은 2026-04-28T03:14:15.000+00:00 형식이에요. v2 웹훅처럼 id, timestamp, data로 감싸지 않아요.
서명 검증
서명 방식은 v2 웹훅과 같아요. webhook-id, webhook-timestamp, webhook-signature 헤더로 Standard Webhooks 서명을 검증하세요. 언어별 검증 코드는 웹훅 개요의 서명 검증에 있어요.
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번 모두 실패하면 이메일 알림에서 웹훅 전송 실패를 켠 멤버에게 메일을 보내요.
전송 기록 확인, 재전송, 재시도 멈추기, 서명 키 교체는 웹훅 개요를 참고하세요.