배송 상태가 변경될 때마다 API를 폴링하는 대신, 웹훅을 사용하면 자동으로 알림을 받을 수 있습니다.

🎯 웹훅의 장점
• 실시간 알림 수신
• 배송 상태 변경 즉시 대응
• 고객 서버에서 폴링 로직 구현 불필요
• 자동으로 상태 변경 알림 수신

웹훅 작동 원리

배송 상태가 변경되면 DeliveryAPI 서버가 여러분의 서버로 HTTP POST 요청을 보냅니다.

배송 접수 → DeliveryAPI 감지 → 웹훅 POST → 여러분의 서버

1단계: 웹훅 엔드포인트 생성

Express.js 예제

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/delivery', (req, res) => {
  const event = req.body;
  
  console.log('웹훅 이벤트:', event);
  
  // 이벤트 타입 체크
  if (event.event !== 'tracking.status_changed') {
    return res.status(400).send('Unknown event type');
  }

  // 상태별 처리
  const { previousStatus, currentStatus, trackingNumber } = event.data;

  console.log(`상태 변경: ${previousStatus} → ${currentStatus}`);

  switch(currentStatus) {
    case 'PICKED_UP':
      console.log('집화 완료:', trackingNumber);
      // 고객에게 집화 알림 발송
      break;

    case 'IN_TRANSIT':
      console.log('배송중:', trackingNumber);
      break;

    case 'OUT_FOR_DELIVERY':
      console.log('배송 출발:', trackingNumber);
      // 고객에게 배송 출발 알림
      break;

    case 'DELIVERED':
      console.log('배송 완료:', trackingNumber);
      // 배송 완료 처리
      break;

    case 'FAILED':
      console.log('배송 실패:', trackingNumber);
      // 관리자 알림
      break;
  }

  // 200 응답 필수! (3초 이내)
  res.status(200).send('OK');
});

app.listen(3000);

2단계: 웹훅 URL 등록

대시보드 또는 API로 웹훅 URL을 등록합니다.

POST https://api.deliveryapi.co.kr/v1/webhooks/endpoints

{
  "url": "https://yourdomain.com/webhooks/delivery",
  "name": "배송 알림 시스템"
}

// 응답
{
  "isSuccess": true,
  "data": {
    "endpointId": "ep_xxx",
    "webhookSecret": "whsec_xxx" // 이 값을 안전하게 보관!
  }
}

웹훅 페이로드 구조

{
  "event": "tracking.status_changed",
  "subscriptionId": "sub_xxx",
  "timestamp": "2026-01-13T10:30:00.000Z",
  "data": {
    "courierCode": "04",
    "trackingNumber": "1234567890",
    "previousStatus": "IN_TRANSIT",
    "currentStatus": "DELIVERED",
    "tracking": {
      // 상세 배송 정보
    }
  },
  "metadata": {
    "orderId": "ORD-12345" // 구독 시 등록한 메타데이터
  }
}

배송 상태 코드

보안: 시그니처 검증

웹훅 요청이 DeliveryAPI에서 온 것인지 검증해야 합니다.

const crypto = require('crypto');

function verifySignature(req) {
  const signature = req.headers['x-deliveryapi-signature'];
  const payload = JSON.stringify(req.body);
  const secret = process.env.WEBHOOK_SECRET;
  
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === hash;
}

app.post('/webhooks/delivery', (req, res) => {
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  
  // 웹훅 처리...
});

재시도 로직

웹훅 전송이 실패하면 자동으로 재시도합니다.

웹훅 전송 재시도 (최대 5회)

💡 참고
택배사 조회 실패 시에는 지수 백오프(2, 4, 8, 16, 30분)로 재시도합니다.
✅ 베스트 프랙티스
• 3초 이내에 200 응답 반환
• 무거운 작업은 백그라운드로 처리
• 중복 이벤트 처리 (idempotency)
• 로그 기록

다음 단계