incento 개발자센터API웹훅
웹훅 개요
리퍼럴 보상 지급 시점에 인센토가 고객사 서버로 이벤트를 전달하는 방식을 안내합니다. 요청에는 X-Incento-Event, X-Incento-Delivery, X-Incento-Signature 헤더가 포함됩니다.
인센토 웹훅은 리퍼럴 보상이 확정될 때 고객사가 등록한 URL로 HTTP POST 요청을 전송합니다. 고객사 서버는 이 요청을 수신하여 해당 회원에게 보상(포인트 적립, 쿠폰 발급 등)을 직접 처리합니다.
웹훅 동작 흐름
주문 동기화
고객사 서버가 POST /api/open/orders/sync/로 주문 데이터를 전달합니다.
리퍼럴 보상 평가
인센토 백엔드가 주문과 연결된 리퍼럴을 확인하고 보상 지급 여부를 평가합니다.
웹훅 전송
보상이 확정되면 등록된 엔드포인트로 reward.issue 이벤트를 POST 합니다.
보상 처리
고객사 서버가 웹훅 페이로드를 수신하고 해당 회원에게 보상을 지급합니다.
웹훅 연결하기
- 웹훅 서명 키(webhook signing key) 조회 — 웹훅 요청이 인센토에서 발송된 것임을 검증하는 데 사용합니다. 가입 시 자동으로 발급되며, 인센토 개발자센터 > 콘솔 > Credentials에서 확인할 수 있습니다.
- 웹훅 등록 — 웹훅 수신 URL은 인센토 개발자센터 > 콘솔 > Webhooks에서 등록할 수 있습니다. 로그인 후 URL과 이벤트 타입을 지정해 등록하세요.
같은 이벤트 타입에 여러 URL을 등록하면, 해당 이벤트 발생 시 모든 URL이 호출됩니다.
웹훅 서명 키 재발급, 삭제 및 웹훅 삭제가 필요한 경우 인센토 팀으로 문의해 주세요.
웹훅 수신 요청 형식
인센토가 등록된 URL로 전송하는 HTTP 요청입니다.
POST https://yourshop.com/webhooks/incento
Content-Type: application/json
X-Incento-Event: reward.issue
X-Incento-Delivery: 550e8400-e29b-41d4-a716-446655440000
X-Incento-Signature: sha256=a1b2c3d4...| 헤더 | 설명 |
|---|---|
X-Incento-Event | 이벤트 타입 (예: reward.issue) |
X-Incento-Delivery | 전송 고유 ID — 중복 수신 방지에 사용하세요 |
X-Incento-Signature | HMAC-SHA256 서명 (sha256=<hex>). 서명 키 미등록 시 포함되지 않습니다 |
웹훅 서명 검증
X-Incento-Signature 헤더를 검증하여 요청이 인센토에서 발송된 것임을 확인합니다.
const crypto = require('crypto');
function verifySignature(secret, rawBody, receivedSignature) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(receivedSignature),
);
}import hashlib
import hmac
def verify_signature(secret: str, raw_body: bytes, received_signature: str) -> bool:
expected = 'sha256=' + hmac.new(
secret.encode(), raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, received_signature)반드시 raw_body(원본 바이트)로 검증하세요. JSON 파싱 후 재직렬화하면 서명이 일치하지 않습니다.
timingSafeEqual / compare_digest를 사용하여 타이밍 공격을 방지하세요.