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-WhereParcel-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)
  );
}

실패 처리

웹훅은 한 번만 전송되며, 자동 재시도는 없습니다.

엔드포인트가 10초 안에 2xx를 반환하지 않거나 DNS·TLS·연결 오류로 도달할 수 없으면 해당 전송은 폐기되며 다시 보내지 않습니다.

따라서 엔드포인트 가용성 확보가 중요합니다. 도움이 되는 방법들입니다:

  • 먼저 2xx를 반환하고, 처리는 백그라운드에서 하세요. 응답 전에 느린 작업 (DB 쓰기, 외부 API 호출)을 하지 마세요.
  • 웹훅 URL 앞에 인증을 두지 마세요. 요청에는 검증용 X-WhereParcel-Signature 헤더가 실릴 뿐 별도 토큰은 없습니다 — 인증 뒤에 있는 엔드포인트는 모든 전송을 401로 거부하게 됩니다.
  • URL을 계속 살려두세요. 호스트를 내리거나 도메인이 만료되면 전송은 조용히 실패합니다.
  • API로 대조하세요. 놓치면 안 되는 건은 GET /v2/webhooks/subscriptions/{requestId}로 현재 상태를 확인하는 편이 웹훅에만 의존하는 것보다 안전합니다.

모범 사례 요약

  1. 빠르게 응답하기 - 10초 이내에 2xx를 반환하세요
  2. 비동기 처리하기 - 응답을 차단하지 마세요
  3. 서명 검증하기 - 항상 X-WhereParcel-Signature를 확인하세요
  4. 중복 처리하기 - 멱등성 키를 활용하세요
  5. 엔드포인트 모니터링하기 - 재시도가 없으므로 다운타임은 곧 알림 유실입니다

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