--- title: "웹훅: Spark! 문서 | Chargezen" description: "실시간 이벤트 알림을 받아요. Chargezen Spark! 문서의 API 참조 섹션에 있어요." url: "https://chargezen.com/ko/docs/spark/api/webhooks" lang: "ko" updated: "2026-01-19" --- Canonical URL: https://chargezen.com/ko/docs/spark/api/webhooks # 웹훅 실시간 이벤트 알림을 받아요 마지막 업데이트: 2026-01-19 웹훅은 Spark!에서 이벤트가 발생하면 애플리케이션에 알려요. 새 주문, 제휴 마케터 가입, 지급 등에 대한 실시간 업데이트를 받아요. ## 웹훅 설정 1. Settings → API → Webhooks로 이동해요 2. "Add Webhook Endpoint"를 클릭해요 3. 엔드포인트 URL을 입력해요(HTTPS 필수) 4. 구독할 이벤트를 선택해요 5. 검증에 사용할 서명 비밀 키를 복사해요 ## 사용 가능한 이벤트 * **affiliate.created** — 새 제휴 마케터 가입 * **affiliate.approved** — 제휴 마케터 승인 * **affiliate.updated** — 제휴 마케터 프로필 변경 * **order.attributed** — 주문에 대한 제휴 마케터의 기여 인정 * **commission.created** — 커미션 계산 * **commission.approved** — 커미션 확정 * **commission.paid** — 커미션 지급 * **payout.created** — 지급 배치 생성 * **payout.completed** — 지급 배치 처리 * **click.recorded** — 제휴 링크 클릭 ## 페이로드 형식 웹훅 페이로드는 다음을 포함한 JSON 객체예요. * `id` — 고유 이벤트 ID * `type` — 이벤트 유형(예: "order.attributed") * `created_at` — ISO 8601 타임스탬프 * `data` — 이벤트별 데이터 객체 멱등성 `id` 필드로 중복 이벤트를 제거하세요. 드물게 같은 이벤트가 여러 번 전달될 수 있어요. ## 웹훅 검증 웹훅 서명을 검증해 진위를 확인해요. 1. `X-Spark-Signature` 헤더를 추출해요 2. 서명 비밀 키로 원본 본문의 HMAC-SHA256을 계산해요 3. 계산한 서명을 헤더 값과 비교해요 4. 일치하지 않는 요청을 거절해요 ## 재시도 정책 엔드포인트가 실패하면(2xx가 아닌 응답) Spark!가 다음과 같이 재시도해요. * 즉시 재시도 * 5분 후 * 30분 후 * 2시간 후 * 24시간 후 5번의 시도가 실패하면 웹훅이 실패로 표시돼요. ## 웹훅 테스트 웹훅 엔드포인트를 테스트해요. * 설정에서 "Send Test Event" 버튼을 사용해요 * 웹훅 전달 로그를 확인해요 * 실패한 전달을 수동으로 재시도해요 ## 다음 단계 [ ### REST 엔드포인트 REST API를 살펴봐요 자세히 보기 ](https://chargezen.com/ko/docs/spark/api/endpoints)[ ### 데이터 내보내기 대량 데이터 내보내기 옵션 자세히 보기 ](https://chargezen.com/ko/docs/spark/analytics/exporting) ### 관련 문서 [ #### REST 엔드포인트 API 엔드포인트 ](https://chargezen.com/ko/docs/spark/api/endpoints)[ #### 인증 API 인증 ](https://chargezen.com/ko/docs/spark/api/authentication) 이 페이지가 도움이 되었나요? 도움이 더 필요하신가요? [고객 지원 문의](https://chargezen.com/ko/docs/checkoutos/troubleshooting/support)