이커머스 배송 알림 시스템 구축 가이드

온라인 쇼핑 고객의 93%가 배송 추적을 전체 쇼핑 경험에서 중요한 요소로 꼽고 있습니다. 고객은 자신의 택배가 지금 어디에 있는지 실시간으로 알고 싶어 합니다. 이 튜토리얼에서는 WhereParcel API를 활용하여 완전한 배송 알림 시스템을 구축하는 방법을 단계별로 안내해 드리겠습니다.

완성될 시스템 개요

이 튜토리얼을 마치면 다음 기능을 갖춘 알림 시스템을 구축하게 됩니다.

  • 주문 발송 시 자동으로 추적 등록
  • 웹훅을 통한 실시간 배송 상태 업데이트
  • 주요 배송 단계에서 이메일/SMS 알림 발송
  • 고객이 직접 확인할 수 있는 추적 페이지

아키텍처 개요

전체 시스템의 데이터 흐름은 다음과 같습니다.

주문 발송 → 추적 등록 → WhereParcel API
                              ↓
                          웹훅 이벤트
                              ↓
                       알림 처리 서비스
                         ↓           ↓
                      이메일         SMS

주문이 발송되면 WhereParcel에 추적 번호를 등록하고, 배송 상태가 변경될 때마다 웹훅으로 알림을 받아 고객에게 전달하는 구조입니다.

1단계: 주문 발송 시 추적 등록

풀필먼트 시스템에서 주문을 발송 처리하면, 해당 운송장 번호를 WhereParcel에 등록합니다.

async function registerTracking(order) {
  const response = await fetch('https://api.whereparcel.com/v2/track', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.WHEREPARCEL_API_KEY}:${process.env.WHEREPARCEL_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      trackingItems: [{ carrier: order.carrier, trackingNumber: order.trackingNumber }],
      webhook: {
        url: 'https://yourapp.com/webhooks/tracking',
        events: ['status_changed', 'delivered', 'exception'],
      },
    }),
  });

  return response.json();
}

webhook 객체에서 수신할 이벤트 유형을 지정합니다. status_changed는 배송 상태가 바뀔 때마다, delivered는 배송 완료 시, exception은 배송 예외 상황 발생 시 알림을 받습니다.

2단계: 웹훅 수신 엔드포인트 구현

WhereParcel이 배송 상태 변경을 전달할 수 있도록 웹훅 엔드포인트를 만듭니다.

app.post('/webhooks/tracking', async (req, res) => {
  // 웹훅 서명 검증
  const signature = req.headers['x-webhook-signature'];
  if (!verifySignature(req.body, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // 즉시 응답 (처리 시간과 관계없이 200을 먼저 반환)
  res.status(200).json({ received: true });

  // 이벤트 비동기 처리
  const { event, data } = req.body;
  await handleTrackingEvent(event, data);
});

중요한 점은 웹훅 요청에 대해 즉시 200 응답을 반환하는 것입니다. 실제 처리 로직은 응답 이후에 비동기로 실행합니다. 이렇게 하면 WhereParcel 서버가 타임아웃으로 불필요한 재전송을 하는 것을 방지할 수 있습니다.

3단계: 이벤트별 알림 처리

배송 상태에 따라 적절한 알림 메시지를 고객에게 발송합니다.

async function handleTrackingEvent(event, data) {
  const order = await findOrderByTracking(data.trackingNumber);
  if (!order) return;

  switch (data.status) {
    case 'picked_up':
      await sendNotification(order.customer, {
        title: '주문하신 상품이 발송되었습니다!',
        body: `${data.location}에서 상품이 픽업되었습니다.`,
      });
      break;

    case 'in_transit':
      await sendNotification(order.customer, {
        title: '상품이 배송 중입니다',
        body: `현재 위치: ${data.location}`,
      });
      break;

    case 'out_for_delivery':
      await sendNotification(order.customer, {
        title: '오늘 배송 예정입니다!',
        body: '상품이 배송 차량에 실려 이동 중입니다.',
      });
      break;

    case 'delivered':
      await sendNotification(order.customer, {
        title: '배송이 완료되었습니다!',
        body: `${data.location}에 배송 완료되었습니다.`,
      });
      break;

    case 'exception':
      await sendNotification(order.customer, {
        title: '배송 안내',
        body: `배송 관련 안내 사항이 있습니다: ${data.description}`,
      });
      break;
  }
}

각 상태별로 고객이 이해하기 쉬운 메시지를 구성하는 것이 핵심입니다. 특히 exception 이벤트는 지연이나 반송 같은 예외 상황이므로, 고객이 불안해하지 않도록 명확하게 안내해야 합니다.

4단계: 고객용 추적 페이지 구현

고객이 직접 배송 현황을 확인할 수 있는 추적 페이지를 만듭니다.

app.get('/track/:trackingNumber', async (req, res) => {
  const { trackingNumber } = req.params;

  const tracking = await fetch(
    'https://api.whereparcel.com/v2/track',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.WHEREPARCEL_API_KEY}:${process.env.WHEREPARCEL_SECRET_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        trackingItems: [{ carrier: 'auto', trackingNumber }],
      }),
    }
  );

  const result = await tracking.json();
  res.render('tracking', { tracking: result.data });
});

carrier 값을 'auto'로 설정하면 WhereParcel이 운송장 번호를 분석하여 택배사를 자동으로 식별합니다. 고객이 택배사를 직접 선택하지 않아도 되므로 사용 편의성이 높아집니다.

5단계: 알림 설정 기능 추가

고객이 원하는 알림 채널과 수신할 이벤트를 직접 설정할 수 있도록 합니다.

const notificationPreferences = {
  email: true,      // 기본 활성화
  sms: false,       // 고객 선택 (opt-in)
  push: false,      // 고객 선택 (opt-in)
  milestones: [     // 알림 받을 이벤트 목록
    'picked_up',
    'out_for_delivery',
    'delivered',
    'exception',
  ],
};

모든 이벤트에 알림을 보내는 것보다, 고객이 중요하게 생각하는 시점에만 알림을 보내는 것이 훨씬 효과적입니다. 기본 설정으로 핵심 마일스톤만 선택하고, 나머지는 고객이 직접 추가할 수 있게 해 주세요.

모범 사례

  1. 과도한 알림은 금물입니다 — 물류 허브를 거칠 때마다 알림을 보내면 고객에게 오히려 피로감을 줍니다. 픽업, 배송 출발, 배송 완료, 예외 상황 등 핵심 마일스톤에만 알림을 보내세요.

  2. 추적 링크를 반드시 포함하세요 — 모든 알림 메시지에 추적 페이지 링크를 넣어 주세요. 고객이 궁금할 때 직접 확인할 수 있으면 CS 문의가 크게 줄어듭니다.

  3. 배송 지연에 사전 대응하세요 — 택배가 48시간 이상 이동이 없으면 고객이 불안해하기 전에 먼저 상황을 안내하는 것이 좋습니다. 고객 신뢰도를 높이는 가장 효과적인 방법입니다.

  4. 시간대를 고려하세요 — 가능하면 수신자의 현지 시간 기준으로 적절한 시간에 알림을 발송하세요. 새벽에 받는 알림은 좋은 경험이 아닙니다.

  5. 국제 배송은 요약 알림을 활용하세요 — 국제 배송은 중간 경유지가 많아 이벤트가 빈번하게 발생합니다. 개별 알림 대신 하루 단위의 요약 알림으로 보내는 것이 바람직합니다.

다음 단계