Webhook 설정 및 관리
웹사이트에서 고객 결제 완료, 상품 배송 또는 도착, 문의 양식 제출, 도메인 인증 실패, 트래픽 목표 달성 등과 같은 이벤트가 발생하면 Kanorio는 Webhook를 통해 해당 데이터를 지정된 URL로 실시간으로 전송할 수 있습니다.
Webhook을 Zapier, Make, n8n 또는 자체 시스템에 연결하면 새로운 주문을 Google Sheets에 자동으로 동기화하거나, 양식 제출 내용을 팀의 Slack/Discord/Telegram 그룹으로 전달하거나, 지원 티켓을 생성하거나, 회사의 ERP 및 CRM과 데이터를 동기화할 수 있습니다.
수신 엔드포인트를 구축하는 엔지니어의 경우: 이 가이드에서는 대시보드 설정, 이벤트 구독, 재시도 규칙 및 문제 해결 방법을 다룹니다. HTTP 헤더,
X-Kanorio-Signature검증 코드 및 8가지 모든 이벤트에 대한 전체 JSON 필드 사양은 Webhook 이벤트 및 서명 검증을 참조하십시오.
시작하기 전에
- 위치: 대시보드의 "Website Settings › Developer › Webhooks"로 이동합니다.
- 엔드포인트 제한: 모든 플랜(무료 플랜, 프로 플랜, 비즈니스 플랜 포함)에서 웹사이트당 최대 10개의 Webhook 엔드포인트를 허용합니다.
- 역할 권한: 소유자와 관리자만 엔드포인트를 추가, 테스트, 수정하고 구독을 변경하며, 페이로드 내용을 확인하고, 수동으로 재시도하며, 서명 키를 표시/교체할 수 있습니다. 다른 팀원은 엔드포인트의 표시 이름과 상태만 볼 수 있으며 URL, 키 또는 전송 로그는 볼 수 없습니다.
Webhook 추가 및 테스트 (5단계)
1. 수신 도구에서 HTTPS URL 가져오기
수신 도구를 열어 Webhook 수신기를 만들고 URL을 복사합니다(URL은 https://로 시작해야 하며 localhost나 내부 네트워크 주소는 사용할 수 없습니다).
- Zapier: 새 Zap을 만들고 트리거로 "Webhooks by Zapier"를 선택한 다음 이벤트로 "Catch Hook"을 선택하고 생성된 Webhook URL을 복사합니다.
- Make: 새 시나리오를 만들고 첫 번째 모듈로 "Webhooks"를 선택한 다음 "Custom webhook"을 선택하고 URL을 복사합니다.
- n8n: "Webhook" 노드를 추가하고 HTTP 메서드를
POST로 설정한 다음 Production/Test URL을 복사합니다. - 자체 시스템: 엔지니어에게
POSTJSON 요청을 수신할 수 있는https://URL을 제공하도록 요청합니다.
2. Kanorio에 엔드포인트 추가
"Website Settings › Developer › Webhooks"로 이동하여 "Add Webhook"을 클릭하고 방금 복사한 URL을 붙여넣은 다음, 알아보기 쉬운 표시 이름(예: "Zapier Order Sync" 또는 "Make Form Forwarding")을 입력하고 "Add Webhook"을 클릭합니다.
3. 서명 키 복사 또는 저장
생성 후 대시보드에는 이 엔드포인트 고유의 "Signature Key"(whsec_로 시작)가 표시됩니다.
- Zapier, Make 또는 n8n을 사용하는 경우: 이러한 도구는 일반적으로 URL 경로에 임의의 키를 포함하므로 서명 검증이 필요하지 않습니다. "Done"을 클릭하면 됩니다.
- 자체 서버를 사용하는 경우: 이 서명 키를 복사하여 엔지니어에게 제공하고 서명 검증을 구현하도록 합니다. 목록에서 엔드포인트를 확장하고 "Show"를 클릭하여 다시 확인하거나, "Generate New Key"를 클릭하여 키를 교체할 수 있습니다.
4. "Send Test"를 클릭하여 연결 확인
목록에서 새로 만든 엔드포인트를 확장하고 "Send Test"를 클릭합니다. 시스템이 즉시 테스트 이벤트(team.test)를 전송합니다.
- 화면에 "Test Successful (HTTP 200, took X ms)"가 표시되고 Zapier/Make/서버가 테스트 데이터를 수신하면 연결에 성공한 것입니다.
- "Send Test"는 공식 전송 로그에 기록되지 않으며 연속 실패 제한 횟수에 포함되지 않으므로 문제 해결 중에 자유롭게 사용하십시오.
5. 구독 이벤트 조정 (선택 사항)
새 엔드포인트는 기본적으로 "All Events"를 구독하도록 설정되어 있습니다. 이 URL이 특정 알림(예: "주문 결제 완료"만)만 수신하도록 하려면 다음 섹션을 참조하십시오.
구독 이벤트 선택
목록에서 엔드포인트를 확장하고 "Subscribed Events" 섹션을 사용하여 다음을 선택합니다.
- All Events (Default): 현재 지원되는 모든 이벤트가 전송되며, 향후 Kanorio에서 추가되는 모든 이벤트도 자동으로 포함됩니다.
- Specific Events: 이 엔드포인트에 필요한 이벤트만 선택하고(최소 하나 이상 선택해야 함) "Save Subscription"을 클릭하여 변경 사항을 즉시 적용합니다.
현재 다음 프로덕션 이벤트와 1개의 테스트 이벤트를 지원합니다(JSON 필드 세부 정보는 Webhook 이벤트 및 서명 검증 참조).
| 이벤트 이름 | 전송 시점 | 이벤트 코드 |
|---|---|---|
| 주문 결제 완료 | 구매자가 결제를 완료하고 주문이 공식적으로 생성되었을 때 (주문당 1회 전송) | ec.order.paid |
| 배송 상태 변경 | 배송 상태가 배송 중, 매장 도착, 배송 완료 또는 배송 예외로 변경되었을 때 | ec.shipment.statusChanged |
| 폼 제출 | 방문자가 온라인 폼을 제출하고 스팸 방지 검사를 통과했을 때 (폼 작성자 정보 및 모든 질문에 대한 전체 답변 포함) | customers.form.submitted |
| 권한 부여/취소 | 구매, 무료 신청 또는 수동 조정을 통해 수강생이 코스나 다운로드 패키지에 대한 액세스 권한을 얻거나 잃었을 때 | deliverables.entitlement.granted / revoked |
| 유닛 완료 | 수강생이 코스 내의 유닛을 완료했을 때 (수강생당 유닛별 1회 전송) | deliverables.progress.unit_completed |
| 코스 완료 | 수강생이 코스 완료 기준을 충족했을 때 (수강생당 코스별 1회 전송) | deliverables.progress.completed |
| 퀴즈 응시 | 수강생이 퀴즈를 제출했을 때 (점수 및 합격/불합격 상태 포함) | deliverables.quiz.attempted |
| 수료증 발급 | 수강생이 수료증을 받았을 때 (수료증 번호 및 발급일 포함; 수강생당 코스별 1회) | deliverables.certificate.issued |
| 컬렉션 항목 변경 | 컬렉션 내의 단일 항목이 생성, 초안으로 업데이트, 게시, 게시 취소 또는 삭제되었을 때 | collections.item.created / updated / published / unpublished / deleted |
| 컬렉션 일괄 변경 | 항목이 일괄 저장되거나, CSV/JSON을 통해 가져오거나, API를 통해 컬렉션에 기록되었을 때 (단일 이벤트로 전송) | collections.items.bulk_changed |
| 번역 게시/제거 | 다국어 사이트 내의 특정 콘텐츠가 개별적으로 게시되거나 제거되었을 때 (예: 수정 후 저장, API 기록 또는 소스 변경 후 자동 번역 등; 전체 사이트 번역 시에는 개별적으로 전송되지 않음) | content.translation.published / deleted |
| 로케일 게시/게시 취소/업데이트 | 로케일이 게시(전체 사이트 번역 완료 또는 수동 게시), 제거, 비활성화되거나 URL 접두사, 자동 번역 토글, 순서 또는 기본 언어가 업데이트되었을 때 | localization.locale.published / unpublished / updated |
| 전체 사이트 번역 완료/실패 | 언어 추가 또는 "누락된 항목 재실행"으로 시작된 전체 사이트 번역이 완료되었을 때 (번역됨, 건너뜀, 실패한 항목 수 포함) | localization.job.completed / failed |
| 발신 도메인 무효화 | 사용자 지정 발신 도메인에 대한 DNS 확인이 실패했을 때 (도메인당 하루 최대 1회) | customers.sendingDomain.degraded |
| 메시징 할당량 알림 | 현재 결제 기간의 이메일 할당량을 모두 소진했거나, 자동 충전이 트리거되었거나, 자동 충전이 한도에 도달했거나, 충전 결제가 실패했을 때 | customers.messagingQuota.alert |
| 스토리지 할당량 알림 | 스토리지 용량이 거의 가득 찼거나, 가득 찼거나, 자동 충전이 트리거되었거나, 자동 충전이 한도에 도달했거나, 충전 결제가 실패했을 때 | site.storageQuota.alert |
| 연간 갱신 알림 | 연간 플랜 갱신 전, 연간 추가 기능이나 미결제 추가 기능/플랫폼 수수료가 있는 경우 (총 합산 청구 금액 미리보기) | site.subscription.upcomingRenewal |
| 추가 기능 가격 변경 알림 | 추가 기능의 가격이 조정되기 전 (최소 30일 전) | site.subscription.addOnPriceChange |
| 트래픽 마일스톤 | 사이트의 누적 순 방문자 수가 100명 또는 500명을 초과했을 때 | site.analytics.milestone |
| 연동 일시 중지 | 연속적인 실패로 인해 시스템이 Webhook 엔드포인트를 자동으로 일시 중지했을 때 (다른 정상적인 엔드포인트에는 알림을 보내지만, 중지된 엔드포인트에는 전송하지 않음) | customers.teamDestination.disabled |
| 액세스 요청 | 팀원이 대시보드에서 권한 부족을 경험하고 액세스 요청을 제출했을 때 (요청당 1회 전송) | team.accessRequest.created |
| 테스트 이벤트 | 패널에서 "테스트 전송"을 클릭했을 때 | team.test |
Webhook과 팀 알림 이메일의 차이
- 독립적인 관리: Webhook 전송 여부는 "Website Settings › Developer › Webhooks" 아래의 각 엔드포인트에 대한 구독 설정에만 전적으로 의존합니다. "Automations › Settings"에서 "Send Webhook"이 "N endpoints subscribed" 또는 "Not connected"로 표시되는지 확인할 수 있지만, 실제 토글은 Webhooks 페이지에서 관리됩니다.
- 팀 이메일을 대체하지 않음: Webhook을 추가한다고 해서 웹사이트 소유자나 팀원에게 전송되는 표준 알림 이메일(예: 새 주문, 양식 회신)이 중단되지는 않습니다. 팀 이메일을 비활성화하고 Webhook만 사용하려면 "Store Notifications" 또는 "Form Confirmation Emails"로 이동하여 팀 이메일 설정을 끄십시오.
- 이메일 할당량에 영향 없음: Webhook은 HTTPS를 통해 외부 URL로 직접 푸시되므로 웹사이트의 월간 이메일 전송 할당량을 소모하지 않습니다.
로그 보기, 수동 재시도 및 자동 일시 중지
최근 전송 내역 및 "Retry" 확인
엔드포인트를 확장하면 "Recent Deliveries" 섹션에 이벤트 이름, 상태(Sent, Failed, Processing), HTTP 상태 코드 및 타임스탬프를 포함한 최근 10개의 알림이 나열됩니다. 기록을 클릭하면 시도 횟수, 소요 시간, 다음 재시도 시간 및 실패 이유를 볼 수 있습니다.
- 내용 보기 (7일 보관): 알림 발생 후 7일 이내라면 "View Content"를 클릭하여 전송된 전체 JSON 페이로드를 볼 수 있습니다.
- 수동 재시도 (7일 보관): 수신기가 일시적으로 다운되었거나 흐름 설정이 방금 수정된 경우, 7일 이내라면 "Retry"를 클릭하여 알림을 다시 푸시할 수 있습니다. 수동 재시도는 동일한 알림 ID를 사용하므로(수신기가 중복을 제거하기 더 쉬움) 수동 재시도가 실패하더라도 백그라운드 재시도를 트리거하거나 자동 일시 중지 제한 횟수에 포함되지 않습니다.
실패 시 자동 재시도 및 일시 중지
수신기가 올바르게 응답하지 않으면 시스템은 응답 상태에 따라 처리합니다.
- 자동 지수 백오프 (최대 8회 시도, 약 2.5일):
수신기가 8초 이내에 응답하지 않거나, 네트워크 오류가 발생하거나, HTTP
429(Too Many Requests) 또는5xx(Server Error)를 반환하면 Kanorio는 백그라운드에서 자동으로 재시도합니다: 1분 → 5분 → 30분 → 2시간 → 8시간 → 24시간 → 24시간, 초기 전송을 포함하여 총 8회 시도합니다. - 재시도 불가능한 오류 (
3xx및 기타4xx): 수신기가 리디렉션(301,302등) 또는 구성 오류(예:400,401,403,404)를 반환하면 시스템은 재시도하지 않으며 1회의 전송 실패로 간주합니다. - 즉시 일시 중지 (
410 Gone): 수신기가410 Gone을 반환하면 URL이 명시적으로 비활성화되었음을 의미하며 시스템은 즉시 엔드포인트를 일시 중지합니다. - 3회 연속 실패 후 자동 일시 중지:
엔드포인트가 3회 연속으로 알림 전송에 실패하면(예: 8회 재시도 모두 소진 또는 3회 연속
404오류), 시스템은 엔드포인트를 "Consecutively Failed, Paused"로 표시하고 푸시를 중단하며, "Manage Integrations" 권한이 있는 멤버(소유자, 관리자 및 이 권한이 있는 사용자 지정 역할)에게 플랫폼 알림과 이메일을 보냅니다. - 다시 활성화하는 방법: 수신기(또는 Zapier/Make 흐름)를 수정한 후 "Website Settings › Developer › Webhooks"로 돌아가 엔드포인트를 확장하고 "Send Test"를 클릭하여 응답을 확인한 다음 "Re-enable"을 클릭하여 푸시를 재개합니다(실패 횟수는 0으로 재설정됨).
일반적인 실패 이유 및 문제 해결
"Send Test" 또는 "Recent Deliveries"에서 실패 메시지가 표시되면 아래 표를 참조하십시오.
| 대시보드 실패 사유 | 의미 | 권장 조치 |
|---|---|---|
| 수신 측이 8초 후 시간 초과됨 | 수신 측이 요청을 처리하는 데 너무 오랜 시간이 걸렸습니다 | 엔지니어에게 요청하여 수신 측을 "요청을 검증한 후 즉시 200 OK를 반환하고, 시간이 걸리는 작업(데이터베이스 기록이나 이메일 전송 등)은 백그라운드에서 처리하도록" 업데이트하세요 |
| 수신 측이 리디렉션을 반환했지만, Kanorio는 이를 따르지 않습니다 | URL이 301, 302, 307 또는 308을 반환했습니다 | 일반적으로 마지막 /가 누락되었거나 추가되었을 때, 또는 도메인이 변경되었을 때 발생합니다. Webhook URL을 최종 https:// URL로 직접 업데이트하세요 |
| 수신 측의 SSL 인증서가 유효하지 않거나 만료되었습니다 | URL에 대한 HTTPS 인증서가 올바르게 설치되지 않았거나, 만료되었거나, 자체 서명되었습니다 | 서버의 SSL/TLS 인증서를 업데이트하세요 (신뢰할 수 있는 공인 인증 기관에서 발급받아야 합니다) |
| 이 URL에 대한 도메인을 찾을 수 없습니다 | DNS가 도메인을 확인할 수 없습니다 | Webhook URL에 오타가 있는지 확인하고 도메인의 DNS A/CNAME 레코드가 활성 상태인지 확인하세요 |
| 수신 측에 연결할 수 없습니다 | 수신 서버가 다운되었거나 방화벽에 의해 차단되었습니다 | 서버가 실행 중인지 확인하고 방화벽이 아래 나열된 두 개의 고정 Kanorio 소스 IP를 허용하는지 확인하세요 |
| 수신 측이 요청을 거부했습니다 (HTTP 401 / 403) | 인증 또는 서명 확인에 실패했습니다 | 사용자 지정 서버를 사용하는 경우 서명 키가 Kanorio 패널의 키와 일치하는지, 그리고 검증에 원본 본문(raw body)이 사용되는지 확인하세요 |
| 수신 측이 이 URL을 찾을 수 없습니다 (HTTP 404) | URL 경로가 존재하지 않거나 Zapier/Make 플로우가 활성화되지 않았습니다 | URL 오타를 확인하세요. n8n 테스트 URL이나 Make를 사용하는 경우 리스너가 활성 상태인지 또는 해당 인터페이스에서 플로우가 공식적으로 활성화되었는지 확인하세요 |
| 수신 측이 요청 빈도를 일시적으로 제한했습니다 (HTTP 429) | 수신 측(또는 Zapier/Make 무료 티어)이 속도 제한에 도달했습니다 | 시스템이 자동으로 재시도를 예약합니다. 이 문제가 자주 발생하면 플랜 제한을 확인하거나 속도 제한을 늘리세요 |
| 수신 측에서 오류가 발생했습니다 (HTTP 5xx) | 내부 서버 오류 (예: 500, 502, 503) | 서버의 오류 로그를 확인하여 문제를 해결한 후 Kanorio에서 "재시도"를 클릭하세요 |
수신기에 방화벽이 있는 경우 (고정 IP 화이트리스트)
모든 Kanorio Webhook 요청(초기 푸시, 테스트 전송, 수동 재시도 및 백그라운드 재시도 포함)은 다음 두 개의 IPv4 주소에서 순환적으로 전송됩니다. 서버나 방화벽에 IP 화이트리스트가 있는 경우 두 IP를 모두 허용하십시오.
| 고정 송신 IP (IPv4) |
|---|
137.184.250.60 |
167.99.28.231 |
보안 참고: IP 화이트리스트는 네트워크 계층의 추가 방어 수단이며 서명 검증을 대체할 수 없습니다. 사용자 지정 수신기에서 항상
X-Kanorio-Signature를 검증하십시오. 향후 송신 IP를 추가하거나 변경해야 하는 경우 이 페이지에서 미리 공지하고 기존 IP와 새 IP의 병행 기간을 유지하겠습니다.
엔지니어에게 전달 (서명 키 및 웹사이트 ID)
내부 또는 외부 엔지니어와 협력하여 수신 프로그램을 개발하는 경우, 대시보드에서 두 가지 정보와 Webhook 이벤트 및 서명 검증 기술 문서 링크만 제공하면 됩니다.
- 엔드포인트 "Signature Key (
whsec_...)": "Website Settings › Developer › Webhooks"에서 엔드포인트를 확장하고 Signature Key 섹션에서 "Show"를 클릭하여 복사합니다.- 키 유출이 의심되거나 주기적인 교체가 필요한 경우: "Generate New Key"를 클릭합니다. 교체 후에도 이전 키는 24시간 동안 유효합니다(이 기간 동안 모든 요청에는 두 키로 계산된 서명이 포함됨). 이를 통해 엔지니어는 중단 없이 서버 설정을 업데이트할 수 있습니다. 24시간 이내에 "Generate New Key"를 다시 클릭하면 이전 키는 즉시 무효화됩니다.
- 웹사이트 ID (
websiteId): 서버가 여러 Kanorio 웹사이트의 Webhook을 수신하는 경우 JSON의websiteId필드를 사용하여 구분할 수 있습니다. "Website Settings › General" 페이지 맨 아래에서websiteId를 복사할 수 있습니다.
지난 7일간의 URL, 서명 키 및 전송 내용은 Google Cloud 봉투 암호화를 사용하여 저장 시 암호화됩니다. 대시보드에서 키가 표시되거나 콘텐츠가 조회될 때마다 감사 로그가 생성됩니다(키 및 자격 증명 저장 방법 참조).
자주 묻는 질문
아니요. Webhook은 무료, 프로, 비즈니스 플랜에서 지원되며 최대 10개의 엔드포인트와 세분화된 이벤트 필터링을 사용할 수 있습니다. 플랜을 변경하거나 취소해도 구성된 URL, 표시 이름, 이벤트 구독 또는 서명 키에는 영향을 주지 않습니다.
수신기가 응답하는 데 8초 이상 걸리거나, 네트워크 장애가 발생하거나, 누군가가 대시보드에서 "Retry"를 클릭하면 동일한 알림이 다시 전송될 수 있습니다. 재시도 및 수동 재시도에는 정확히 동일한 알림 ID(헤더 X-Kanorio-Delivery 및 JSON id)가 포함됩니다. 엔지니어 또는 자동화 흐름에서 이 ID를 사용하여 중복 여부를 확인하도록 하십시오.
Kanorio는 현재 표준 JSON 형식의 일반 Webhook을 푸시합니다. Slack, Discord, Telegram, Microsoft Teams 또는 Google Sheets로 데이터를 전달하려면 Webhook을 먼저 Zapier, Make 또는 n8n에 연결하고 해당 도구에서 데이터를 형식화하여 팀의 선호하는 커뮤니케이션 도구로 전달하는 것을 권장합니다.
Webhook 이벤트 및 서명 검증에서 각 이벤트에 대한 전체 JSON 예시를 참조하거나, Webhook 엔드포인트를 만들고 "Send Test"를 클릭하십시오. 또는 사이트에서 실제 이벤트(예: 테스트 양식 제출)가 발생한 후 대시보드의 "Recent Deliveries" 아래에 있는 "View Content"를 클릭하여 실제 JSON 페이로드를 볼 수 있습니다.