Webhook

수신 측의 2xx 응답은 성공으로 간주되며 응답 본문은 무시됩니다. 8초 이내에 응답하십시오. 더 긴 처리가 필요한 경우 먼저 200을 반환하고 비동기적으로 처리하십시오. Kanorio는 리디렉션을 따르지 않으며 3xx 응답은 실패로 처리됩니다.

공통 구조

모든 이벤트 JSON은 동일한 셸을 공유하므로 수신 측은 한 번만 구성하면 됩니다.

{
  "version": "1",
  "id": "3f9c2a…",
  "event": "ec.order.paid",
  "occurredAt": "2026-09-29T12:00:00.000Z",
  "websiteId": "cmk…",
  "title": "New order #1024, NT$1,280",
  "summary": "'My Store' received a paid order.",
  "fields": [{ "label": "Order ID", "value": "#1024" }],
  "data": { "…": "Varies by event, see reference below" },
  "actionUrl": "https://app.kanorio.com/store/transactions?tx=…"
}

이벤트 참조

다음은 각 이벤트의 data 필드입니다. 'Nullable'은 필드가 null일 수 있음을 의미합니다.

ec.order.paid 주문 결제 완료

구매자가 결제를 완료했을 때 전송됩니다(주문당 1회).

ec.shipment.statusChanged 배송 업데이트

배송이 발송, 도착, 배송 완료 또는 예외 상태가 될 때 전송됩니다(배송당 상태 변경 시 1회).

customers.form.submitted 양식 제출

방문자가 양식을 제출하고 스팸 검사를 통과했을 때 전송됩니다(제출당 1회).

answers[] 항목:

customers.sendingDomain.degraded 발송 도메인 저하

인증된 사용자 지정 발송 도메인의 인증이 실패했을 때 전송됩니다(도메인당 하루 1회).

customers.messagingQuota.alert 메시징 할당량 경고

할당량 상태가 변경될 때 전송됩니다.

site.analytics.milestone 트래픽 마일스톤

누적 사이트 조회수가 마일스톤을 넘을 때 전송됩니다(마일스톤당 1회).

customers.teamDestination.disabled 통합 일시 중지

Webhook 엔드포인트가 자동으로 일시 중지될 때 전송됩니다(연속 실패 또는 410 응답). 다른 정상적인 엔드포인트에만 전송됩니다.

team.test 테스트 이벤트

'테스트 보내기'가 클릭될 때 전송됩니다(1회, 재시도 없음, 전달 기록에 기록되지 않음).

Kanorio 요청 확인하기

확인 단계:

1. X-Kanorio-Signature에서 t와 모든 v1을 추출합니다.
2. t, 마침표, 원시 요청 본문(파싱되지 않고 재직렬화된 상태)을 연결합니다(예: 1790000000.{"version":"1",…}).
3. 서명 시크릿을 사용하여 문자열의 HMAC-SHA256(16진수)을 계산하고 v1과 비교합니다. 일치하는 경우에만 수락하십시오.
4. 리플레이 공격을 방지하기 위해 5분 이상 지난 타임스탬프가 있는 요청은 거부하십시오. 재시도 및 재전송은 현재 타임스탬프를 사용하므로 이 제한을 완화할 필요가 없습니다.

Node.js 예시:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = header.split(",").map((part) => part.split("="));
  const t = parts.find(([key]) => key === "t")?.[1];
  const signatures = parts.filter(([key]) => key === "v1").map(([, value]) => value);
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return signatures.some(
    (v1) => v1.length === expected.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
  );
}

Zapier, Make, n8n과 같은 서비스는 일반적으로 사용자 지정 확인 로직을 지원하지 않으며, 수신 URL에 임의의 경로가 포함되어 있으므로 확인은 일반적으로 필요하지 않습니다.

서명 시크릿 교체

시크릿은 통합 목록에서 엔드포인트를 확장하고 '보기'를 클릭하여 확인할 수 있습니다. 유출이 의심되면 '새 시크릿 생성'을 클릭하십시오:

• 이전 시크릿은 24시간 동안 유효합니다. 이 시간 동안 각 요청에는 새 서명과 이전 서명이 모두 포함되며(두 개의 v1), 하나라도 일치하면 충분합니다.
• 24시간 이내에 수신 측을 새 시크릿으로 업데이트하십시오. 패널에 이전 시크릿의 만료 시간이 표시됩니다.
• 24시간 이내에 '새 시크릿 생성'을 다시 클릭하면 이전 시크릿이 즉시 무효화됩니다.

관련 문서

• 개발자
• 자동화
• 기록: 고객 및 팀에게 전송된 모든 알림 보기
• 가격 비교