메인 콘텐츠로 건너뛰기

​
웹훅

웹훅은 스토어에서 이벤트가 발생할 때 애플리케이션에 알림을 보냅니다 — 주문 확인, 결제 완료, 재고 부족 알림 등.

​
설정 방법

Admin API를 통해 웹훅을 생성합니다: 
curl -X POST https://api.headlesscommerce.io/v1/admin/webhooks \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "events": ["order.confirmed", "payment.completed"]
  }'
응답에는 웹훅 서명을 검증하기 위한 secret이 포함됩니다.

​
이벤트 유형

이벤트설명
product.created상품이 생성됨
product.updated상품이 수정됨
product.deleted상품이 삭제됨
order.created주문이 생성됨
order.confirmed주문이 확인됨 (결제 완료)
order.completed주문이 완전히 완료됨
order.cancelled주문이 취소됨
payment.completed결제가 성공적으로 처리됨
payment.failed결제 시도가 실패함
payment.refunded결제가 환불됨
fulfillment.created출고가 생성됨
fulfillment.shipped출고가 발송됨
fulfillment.delivered출고가 배달 완료됨
inventory.low재고가 안전 재고 아래로 떨어짐
inventory.out_of_stock가용 재고가 0이 됨
customer.created고객이 생성됨

​
페이로드 형식

{
  "id": "evt_abc123",
  "type": "order.confirmed",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "id": "order_001",
    "number": 1001,
    "status": "confirmed",
    "total": { "amount": 78000, "currency": "KRW" }
  },
  "store_id": "store_001"
}

​
서명 검증

각 웹훅 전송에는 X-Webhook-Signature 헤더(HMAC-SHA256)가 포함됩니다. 페이로드의 진위를 확인하기 위해 검증하세요: 
import crypto from 'node:crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

​
재시도 정책

실패한 전송은 지수 백오프로 재시도됩니다:
시도지연 시간
1차즉시
2차5분
3차30분
4차2시간
5차24시간
5회 연속 실패 후 웹훅이 비활성화되며 대시보드 알림이 전송됩니다.

​
테스트

엔드포인트를 검증하기 위해 테스트 이벤트를 전송합니다: 
curl -X POST https://api.headlesscommerce.io/v1/admin/webhooks/{id}/test \
  -H "Authorization: Bearer sk_test_your_key"