🔔 웹훅 구독 API 가이드 - 택배 상태 변경 자동 알림

개요

웹훅 구독 API를 사용하면 택배사 송장번호를 등록하고, 배송 상태가 변경될 때마다 자동으로 알림을 받을 수 있습니다. 폴링(Polling) 방식 대신 이벤트 기반으로 알림을 받으므로 서버 리소스를 절약하고 실시간으로 배송 정보를 업데이트할 수 있습니다.

주요 특징

• 자동 폴링: 1시간 고정 주기 (22:00~07:00 KST 야간 중단)
• 상태 변경 알림: 상태가 변경될 때만 웹훅 발송
• 선택적 구독: 원하는 상태(예: 배송중, 배송완료)만 알림 받기 가능
• Dual ID 지원: 서버 생성 ID 또는 클라이언트 지정 ID로 관리
• 보안 서명: HMAC-SHA256 서명으로 웹훅 검증
• 자동 재시도: 실패 시 최대 5회까지 자동 재시도

폴링 정책

폴링 주기

모든 활성 상태에 대해 1시간 주기로 폴링합니다.

야간 중단 (KST 기준)

• 주간 (07:00~22:00): 1시간 주기로 폴링
• 야간 (22:00~07:00): 폴링 일시 중단 — 택배사 시스템 유지보수 시간대

14일 자동 중단

구독 등록 후 14일이 경과하면 자동으로 폴링이 중단됩니다. 장기간 배송되지 않는 건에 대한 불필요한 조회를 방지하기 위한 정책입니다.

1단계: 웹훅 URL 사전 등록

구독을 등록하기 전에, 알림을 받을 웹훅 URL을 먼저 등록해야 합니다. API Key당 최대 10개까지 등록 가능합니다.

요청 예시

curl -X POST "https://api.deliveryapi.co.kr/v1/webhooks/endpoints" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer __API_KEY__:__SECRET_KEY__" \
  -d '{
    "url": "https://your-domain.com/webhook",
    "name": "주문 시스템"
  }'

응답 예시

{
  "isSuccess": true,
  "data": {
    "endpointId": "ep_6b78d0e9eac154e129847aae",
    "url": "https://your-domain.com/webhook",
    "name": "주문 시스템",
    "webhookSecret": "whsec_91289c5160ec743e0721b4a23fb5d33c",
    "dateCreated": "2026-01-13T10:30:33.292Z"
  }
}

2단계: 구독 등록

등록한 웹훅 URL의 endpointId를 사용하여 송장번호를 구독합니다. 1회 요청으로 최대 100건까지 일괄 등록 가능합니다.

요청 예시

curl -X POST "https://api.deliveryapi.co.kr/v1/webhooks/register" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer __API_KEY__:__SECRET_KEY__" \
  -d '{
    "endpointId": "ep_6b78d0e9eac154e129847aae",
    "items": [
      {
        "courierCode": "cj",
        "trackingNumber": "123456789012",
        "clientId": "order-001"
      }
    ],
    "recurring": true,
    "metadata": { "orderId": "ORD-001" }
  }'

요청 필드 설명

응답 예시

{
  "isSuccess": true,
  "data": {
    "requestId": "req_cb0d4e05b5ca97f777b72215",
    "itemCount": 1,
    "recurring": true
  },
  "message": "추적 요청이 등록되었습니다. 결과는 웹훅으로 수신하거나 requestId로 조회할 수 있습니다."
}

3단계: 웹훅 수신 및 검증

배송 상태가 변경되면 등록한 URL로 웹훅이 전송됩니다.

웹훅 페이로드

{
  "event": "tracking.polled",
  "requestId": "req_cb0d4e05b5ca97f777b72215",
  "timestamp": "2026-01-13T10:30:00.000Z",
  "data": {
    "courierCode": "cj",
    "trackingNumber": "123456789012",
    "clientId": "order-001",
    "previousStatus": "IN_TRANSIT",
    "currentStatus": "DELIVERED",
    "hasChanged": true,
    "isDelivered": true,
    "trackingData": {
      "courierCode": "cj",
      "courierName": "CJ대한통운",
      "trackingNumber": "123456789012",
      "deliveryStatus": "DELIVERED",
      "isDelivered": true,
      "progresses": [...]
    }
  },
  "metadata": { "orderId": "ORD-001" }
}

보안 서명 검증 (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(req, webhookSecret) {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const body = JSON.stringify(req.body);

  // 타임스탬프 검증 (5분 이내)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return false;
  }

  // HMAC 서명 계산
  const payload = `${timestamp}.${body}`;
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(payload)
    .digest('hex');

  return `sha256=${expectedSignature}` === signature;
}

4단계: 구독 관리

구독 목록 조회

curl "https://api.deliveryapi.co.kr/v1/webhooks/subscriptions?status=active&limit=20" \
  -H "Authorization: Bearer __API_KEY__:__SECRET_KEY__"

구독 상세 조회

# requestId로 조회
curl "https://api.deliveryapi.co.kr/v1/webhooks/subscriptions/req_cb0d4e05b5ca97f777b72215" \
  -H "Authorization: Bearer __API_KEY__:__SECRET_KEY__"

구독 취소

curl -X DELETE "https://api.deliveryapi.co.kr/v1/webhooks/subscriptions/req_cb0d4e05b5ca97f777b72215" \
  -H "Authorization: Bearer __API_KEY__:__SECRET_KEY__"

폴링 주기 정책

구독한 송장은 1시간 주기로 자동 조회됩니다. 야간(22:00~07:00 KST)에는 폴링이 일시 중단됩니다.

실패 처리 및 재시도

1. 웹훅 전송 실패 시

2. 택배 조회 실패 시 (크롤러 오류)

택배사 웹사이트 조회 실패 시 지수 백오프(Exponential Backoff) 방식으로 재시도합니다.

• 1차 실패: 2분 후
• 2차 실패: 4분 후
• 3차 실패: 8분 후
• 4차 실패: 16분 후
• 5차 실패: 30분 후 (최대값)
• 5회 연속 실패: status='failed'로 변경

베스트 프랙티스

• Idempotency: 같은 이벤트가 중복 전송될 수 있으므로, requestId + timestamp로 중복 체크
• 빠른 응답: 웹훅 수신 시 즉시 200 응답 후 비동기로 처리 (3초 이내 응답 권장)
• 서명 검증: 모든 웹훅에 대해 HMAC 서명 검증 필수
• Client ID 활용: 자체 주문번호를 clientId로 사용하면 별도 매핑 테이블 불필요
• recurring 활용: 실시간 추적이 필요하면 recurring: true (14일 구독), 한 번만 확인하면 recurring: false

테스트 방법

1. webhook.site에서 무료 테스트 URL 생성
2. 생성된 URL로 웹훅 엔드포인트 등록
3. 실제 송장번호로 구독 등록
4. webhook.site에서 실시간으로 웹훅 수신 확인
5. 웹훅 테스트 페이지에서 직접 테스트 가능

다음 단계

• 웹훅 API 실시간 테스트
• 택배 조회 API 테스트
• 무료 API 키 발급
• 기술 지원 문의