택배 추적을 위한 Webhook 모범 사례

Webhook을 사용하면 소포의 상태가 변경될 때 애플리케이션에서 실시간 업데이트를 받을 수 있습니다. API를 반복적으로 폴링하는 대신, 업데이트가 자동으로 전달되도록 설정할 수 있습니다.

Webhook을 사용해야 하는 이유

  • 실시간 업데이트 - 소포 상태가 변경되는 즉시 확인 가능
  • API 호출 감소 - 몇 분마다 폴링할 필요 없음
  • 향상된 사용자 경험 - 고객에게 즉각적인 알림 제공
  • 비용 효율적 - API 사용량이 줄어들어 비용 절감

Webhook 엔드포인트 설정하기

Webhook 엔드포인트는 다음 요건을 충족해야 합니다:

  1. POST 요청을 수신할 수 있어야 합니다
  2. 5초 이내에 200 상태 코드를 반환해야 합니다
  3. 중복 이벤트를 적절히 처리할 수 있어야 합니다
// Express.js example
app.post('/webhooks/whereparcel', (req, res) => {
  const { event, data } = req.body;

  // Always respond quickly
  res.status(200).json({ received: true });

  // Process the event asynchronously
  processTrackingEvent(event, data);
});

보안: Webhook 서명 검증

모든 Webhook 요청에는 X-Webhook-Signature 헤더가 포함됩니다. 요청이 WhereParcel에서 전송된 것인지 확인하기 위해 반드시 이 서명을 검증하세요:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

실패 처리

엔드포인트를 사용할 수 없는 경우, WhereParcel은 지수 백오프(Exponential Backoff) 방식으로 재시도합니다:

시도대기 시간
1차 재시도1분
2차 재시도5분
3차 재시도30분
4차 재시도2시간
5차 재시도12시간

5회 재시도 실패 후 해당 Webhook은 실패로 표시되며, 이메일 알림을 받게 됩니다.

모범 사례 요약

  1. 빠르게 응답하기 - 5초 이내에 200을 반환하세요
  2. 비동기 처리하기 - 응답을 차단하지 마세요
  3. 서명 검증하기 - 항상 X-Webhook-Signature를 확인하세요
  4. 중복 처리하기 - 멱등성 키를 활용하세요
  5. 엔드포인트 모니터링하기 - 실패에 대한 알림을 설정하세요

자세한 내용은 Webhook API 문서를 참고하세요.