택배 추적을 위한 Webhook 모범 사례
WhereParcel을 활용한 택배 추적 자동 알림을 위한 안정적인 Webhook 엔드포인트 설정 방법을 알아보세요.
WhereParcel Team
Webhook을 사용하면 폴링 없이 애플리케이션에서 소포 상태 업데이트를 받을 수 있습니다. 소포를 등록하면 WhereParcel이 배송 완료까지(최대 10일) 약 12시간마다 다시 조회하고, 조회할 때마다 최신 상태를 엔드포인트로 보냅니다.
Webhook을 사용해야 하는 이유
- 자동 업데이트 - 구독한 소포를 약 12시간마다 다시 조회해 보내 드립니다
- API 호출 감소 - 등록할 때 한 번만 차감되고, 이후 조회는 무료입니다
- 향상된 사용자 경험 - 상태 변화를 고객에게 자동으로 알릴 수 있습니다
- 비용 효율적 - API 사용량이 줄어들어 비용 절감
Webhook 엔드포인트 설정하기
Webhook 엔드포인트는 다음 요건을 충족해야 합니다:
POST요청을 수신할 수 있어야 합니다- 5초 이내에
200상태 코드를 반환해야 합니다 - 중복 이벤트를 적절히 처리할 수 있어야 합니다
// 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}로 현재 상태를 확인하는 편이 웹훅에만 의존하는 것보다 안전합니다.
모범 사례 요약
- 빠르게 응답하기 - 10초 이내에 2xx를 반환하세요
- 비동기 처리하기 - 응답을 차단하지 마세요
- 서명 검증하기 - 항상
X-WhereParcel-Signature를 확인하세요 - 중복 처리하기 - 멱등성 키를 활용하세요
- 엔드포인트 모니터링하기 - 재시도가 없으므로 다운타임은 곧 알림 유실입니다
자세한 내용은 API 문서를 참고하세요.
원하는 택배사가 없으신가요? 요청해 주시면 빠르게 연동해 드립니다.
택배사 요청하기 →더 알아보기
궁금한 게 있으세요? 편하게 물어보세요. Discord에 들어오시면 WhereParcel을 만든 개발자가 직접 읽고 답장드립니다. 봇도 없고 티켓도 없어요. 그냥 편하게 대화하세요.
Discord 참여하기 → Slack 참여하기 →