Qnector
로그인

Webhook 연동

Discord·Slack 등 메신저 Incoming Webhook으로 알림을 받거나, 자체 서버에서 연결 테스트·서명 검증을 설정할 수 있습니다.

지원 프로그램 (Incoming Webhook)

아래 서비스의 공식 Incoming Webhook URL을 등록하면, 큐넥터가 URL을 자동 인식해 각 서비스 문서에 맞는 메시지 형식으로 알림을 보냅니다. 별도 포맷 설정은 필요 없습니다.

Webhook Secret은 자체 서버 연동에만 사용됩니다. Discord·Slack·잔디 등 메신저 URL에는 Secret을 등록할 필요가 없습니다.

구분설명

Discord

Discord 채널 Incoming Webhook. URL만 등록하면 알림 메시지가 전송됩니다. (URL 예: discord.com/api/webhooks/...)

Slack

Slack Incoming Webhook. 앱에서 발급한 Webhook URL을 사용합니다. (URL 예: hooks.slack.com/services/...)

잔디(JANDI)

잔디 커넥트 Incoming Webhook. body·connectColor 형식으로 전송됩니다. (URL 예: wh.jandi.com/connect-api/webhook/...)

Google Chat

Google Chat 스페이스 Incoming Webhook. text 필드로 메시지를 보냅니다. (URL 예: chat.googleapis.com/v1/spaces/.../messages)

Microsoft Teams

Teams 채널·워크플로 Webhook. Adaptive Card 형식으로 알림을 보냅니다. (URL 예: webhook.office.com/... 또는 Power Automate 워크플로 URL)

Mattermost / Rocket.Chat

자체 호스팅 협업 도구 Incoming Webhook. text 필드 메시지를 지원합니다. (URL 예: https://{호스트}/hooks/...)

카카오워크

카카오워크 Incoming Webhook. text·blocks(Block Kit) 형식을 지원합니다. (URL 예: 카카오워크 확장 서비스 > Incoming Webhook URL)

알림 Webhook 설정

  • 메신저 URL은 알림(주문·문의 등) 발송에 사용됩니다.
  • 자체 서버 URL은 연결 테스트(webhook_test)와 알림 설정에서 켠 항목을 JSON·서명 헤더 형식으로 받을 수 있습니다.
구분설명

① Webhook URL 등록

대시보드 > API 연동설정 > API 키발급 > Webhook URL에 Incoming Webhook 주소를 저장합니다.

② 연결 테스트

저장 후 「연결 테스트」로 메신저 수신을 확인합니다.

③ 알림 채널 ON

대시보드 > 알림톡 수/발신 내역 > 알림 설정에서 Webhook 전역·개별 알림을 켭니다.

알림 이벤트 (메신저 Webhook)

알림 설정에서 Webhook 채널이 켜진 항목만 해당 이벤트가 메신저로 전달됩니다.

구분설명

new_order

주문 접수

order_status_changed

주문 상태 변경(처리중·완료·취소 등)

order_cancellation_requested

주문 취소 요청

inquiry_created

문의 등록

out_of_stock_depleted

품절 품목 재고 소진

system_announcement

공지 등록

자체 서버 URL 등록

ERP·WMS·자동화 서버 등 직접 만든 수신 엔드포인트는 Qnector API JSON과 서명 헤더로 이벤트를 받습니다.

구분설명

① 경로

대시보드 > API 연동설정 > API 키발급 > Webhook URL

② URL

https:// 만 허용. localhost·사설 IP는 거부됩니다.

③ Secret

저장 시 1회 표시. 수신 서버에 등록해 아래 「서명 검증」에 사용합니다. (메신저 Incoming Webhook에는 불필요)

④ 테스트

저장 후 연결 테스트로 수신을 확인할 수 있습니다.

전달 헤더

구분설명

X-Qnector-Event

이벤트 타입 (예: webhook_test, new_order)

X-Qnector-Delivery-Id

전달 ID (재시도 시 동일)

X-Qnector-Timestamp

Unix seconds

X-Qnector-Signature

sha256= + HMAC-SHA256(secret, timestamp + "." + rawBody)

X-Qnector-Api-Version

2026-06-26

페이로드 예시

json
{
  "api_version": "2026-06-26",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "webhook_test",
  "created_at": "2026-06-26T12:00:00Z",
  "data": {
    "seller_id": "seller-uuid",
    "message": "Qnector webhook test",
    "triggered_at": "2026-06-26T12:00:00Z"
  }
}

서명 검증

rawBody는 JSON 문자열 원문 그대로 사용합니다. 파싱 후 재직렬화하면 서명이 달라질 수 있습니다.

javascript
import crypto from "crypto";

export function verifyQnectorWebhook(req, rawBody, secret) {
  const timestamp = req.headers["x-qnector-timestamp"];
  const signature = req.headers["x-qnector-signature"] || "";

  if (!timestamp || !signature.startsWith("sha256=")) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const received = signature.slice("sha256=".length);

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex"),
  );
}

재시도·멱등

  • 2xx 이외 응답 시 지수 백오프로 재시도합니다(기본 최대 3회, 타임아웃 10초).
  • 동일 event_id가 중복 수신될 수 있으므로 멱등 처리 후 200을 반환하세요.