Webhook 배송 추적: 추적 Webhook이 폴링과 비교해 작동하는 방식(페이로드, 재시도 및 설정)

17TRACK2026-10-29 18:03

배송 추적 웹훅은 추적 서비스에 보고할 업데이트가 있을 때 애플리케이션으로 HTTP 요청을 보냅니다. 폴링은 반대 방향으로 작동합니다. 애플리케이션이 최신 추적 정보를 반복적으로 요청합니다. 배송 데이터를 주문 관리 시스템, 스토어 또는 고객 알림 서비스에 연결하는 개발자에게는 일반적으로 웹훅을 지원하는 경우 웹훅이 더 나은 기본 업데이트 메커니즘입니다. 대상 지정 폴링은 누락된 업데이트를 복구하고 기록을 대조하는 데 도움이 될 수 있습니다.

어느 방법도 운송업체가 소포를 더 빨리 스캔하도록 만들지는 않습니다. 두 방법 모두 추적 소스가 새로운 정보를 수신하고 공개하는 시점에 따라 달라집니다. 실질적인 차이는 애플리케이션이 해당 정보를 알아내는 방식, 생성하는 요청 트래픽의 양, 그리고 전송이 실패했을 때 발생하는 일입니다.

추적 웹훅과 폴링의 비교: 운영상의 차이

이는 경쟁하는 추적 데이터베이스가 아니라 통합 패턴입니다. 운송업체나 추적 플랫폼은 액세스 조건을 달리하여 어느 한 패턴 또는 두 패턴을 모두 제공할 수 있습니다. 모든 웹훅 서비스가 동일한 보장을 제공한다고 가정하지 말고, 사용하려는 특정 API의 동작을 비교하세요.

판단 기준	웹훅	폴링
누가 요청을 시작하나요?	추적 서비스가 사용자의 엔드포인트를 호출합니다.	애플리케이션이 추적 API를 호출합니다.
업데이트 지연	소스의 최신성, 이벤트 생성, 전송 및 처리에 따라 달라집니다.	다음 예약 요청이 실행되는 시점에도 영향을 받습니다.
요청량	생성된 업데이트, 일괄 처리 및 전송 재시도에 따라 결정됩니다.	배송 건수, 폴링 빈도 및 일괄 처리에 따라 결정됩니다.
인프라	접근 가능한 수신기와 보안이 적용된 인바운드 요청 처리가 필요합니다.	스케줄러, 아웃바운드 API 액세스 및 속도 제한 처리가 필요합니다.
장애 복구	제공업체의 재시도와 자체 대조 프로세스에 따라 달라집니다.	후속 요청 및 API가 필요한 기록을 보존하는지 여부에 따라 달라집니다.

적시 업데이트가 중요하고 팀이 안정적인 수신기를 운영할 수 있다면 웹훅을 우선 선택하세요. 인바운드 엔드포인트가 실용적이지 않거나 배송량이 적거나 소스가 적절한 웹훅을 제공하지 않는다면 폴링을 우선 선택하세요. 누락된 업데이트가 고객 커뮤니케이션이나 운영을 방해할 수 있고 API가 대조를 지원한다면 하이브리드 설계를 사용하세요.

웹훅이 더 저렴하다고 가정하지 마세요. 구독 요금, 추적 등록, API 호출, 이벤트 전송 및 인프라에는 서로 다른 요금이 부과될 수 있습니다. 요청 수가 적다는 이유만으로 요금이 낮다고 판단하지 말고 실제 상업적 조건과 예상 작업량을 비교하세요.

운송업체의 스캔과 애플리케이션 사이에는 어떤 일이 발생하나요?

배송을 식별합니다. 추적 번호, 필요한 경우 운송업체 정보 및 내부 배송 참조를 연결합니다. 일부 서비스는 모니터링을 시작하기 전에 등록을 요구합니다.
이벤트 전송을 구성합니다. HTTPS 콜백 URL을 제공하고 지원되는 이벤트 구독을 선택합니다.
소스가 추적 정보를 수신합니다. 운송업체의 스캔 또는 상태 변경이 추적 서비스에서 이용 가능해집니다.
서비스가 웹훅을 전송합니다. 요청에는 전체 추적 스냅샷, 단일 체크포인트 또는 API 조회가 필요한 참조만 포함될 수 있습니다.
수신기가 이를 검증하고 저장합니다. 요청을 인증하고 구조를 확인한 다음 이벤트를 영구적으로 기록하거나 큐에 넣습니다.
워커가 비즈니스 시스템을 업데이트합니다. 상태를 정규화하고 배송 기록을 업데이트하며 여전히 적절한 작업만 실행합니다.

웹훅 전송은 실제 배송과 동일하지 않습니다. 이는 배송 정보에 관한 메시지입니다. 마찬가지로 웹훅에 성공적으로 응답했다고 해서 이메일이 전송되었거나 주문 기록이 업데이트되었다는 의미는 아닙니다. 이러한 작업은 자체 모니터링이 필요한 후속 처리 결과입니다.

추적 웹훅 페이로드 읽기

다음 JSON은 예시적인 통합 설계일 뿐이며 17TRACK 페이로드나 범용 스키마가 아닙니다. 실제 필드 이름, 상태 코드, 타임스탬프 형식 및 이벤트 식별자는 선택한 제공업체의 문서에서 확인해야 합니다.

{
  "event_id": "evt_example_001",
  "event_type": "shipment.updated",
  "created_at": "2025-04-08T10:16:00Z",
  "shipment": {
    "reference": "shipment_example_123",
    "tracking_number": "EXAMPLE123456",
    "carrier_code": "example_carrier",
    "status": "in_transit",
    "checkpoint": {
      "occurred_at": "2025-04-08T10:10:00Z",
      "description": "Departed processing facility"
    }
  }
}

데이터 모델에서 세 가지 시계를 구분하세요. 배송 이벤트가 발생한 시점, 제공업체가 메시지를 생성한 시점, 애플리케이션이 메시지를 수신한 시점입니다. 지연된 체크포인트가 더 최신인 체크포인트 이후에 도착할 수 있습니다. 오프셋이 없는 타임스탬프도 명시적으로 해석해야 합니다. 모든 운송업체 현지 시간 타임스탬프를 UTC로 조용히 처리하지 마세요.

제공업체의 식별자와 함께 내부 배송 참조를 유지하세요. 특히 서로 다른 운송업체 컨텍스트에서는 추적 번호만으로 영구적인 전역 식별자를 삼기에 충분하지 않을 수 있습니다. 분할 주문의 경우 한 소포의 배송 완료 상태가 전체 주문을 완료로 표시하지 않도록 배송 단위 기록을 유지하세요.

정규화된 비즈니스 상태와 함께 원래 상태 및 설명을 보존하세요. 애플리케이션이 여러 운송업체 메시지를 ‘운송 중’으로 매핑하더라도 지원 담당자는 지연을 이해하기 위해 원래 체크포인트가 필요할 수 있습니다. 예상 배송일은 추정치로 취급하고, 필드가 누락된 경우와 기존 값을 삭제하라는 명시적 지시를 구분하세요.

재시도, 승인 및 중복 이벤트

웹훅 전송은 시간 초과, 네트워크 중단, 인증 오류 또는 수신기 이용 불가로 인해 실패할 수 있습니다. 제공업체가 재시도할 수 있지만 보편적인 재시도 일정, 보존 기간 또는 최대 시도 횟수는 없습니다. 어떤 응답이 재시도를 유발하는지, 리디렉션이 어떻게 처리되는지, 수동 재전송이 가능한지 확인하세요.

영구적으로 수락한 후 승인하기

요청 경로를 짧게 유지하세요. 요청을 검증하고, 수락한 작업을 저장한 다음, 제공업체가 요구하는 성공 응답을 반환합니다. 이메일 전송과 느린 비즈니스 작업은 비동기적으로 수행하세요. HTTP 사양에서 202 Accepted는 처리가 완료되었다는 의미가 아니라 처리를 위해 수락했다는 의미이지만, 제공업체가 다른 성공 응답을 요구할 수 있습니다. 해당 웹훅 계약을 따르세요.

아무것도 저장하기 전에 성공을 반환하면 프로세스가 중단될 경우 업데이트가 손실될 위험이 있습니다. 모든 후속 작업이 끝날 때까지 기다리면 시간 초과와 재전송이 발생할 수 있습니다. 영구 인박스 또는 큐는 수신과 처리 사이의 경계를 제공합니다.

처리를 멱등적으로 만들기

멱등성이란 동일한 이벤트를 다시 처리해도 비즈니스 효과가 반복되지 않는다는 의미입니다. 서버가 이벤트를 수락했지만 승인 응답이 손실된 후 발신자가 재시도할 수 있습니다. 따라서 중복 전송은 일반적인 테스트 사례로 다뤄야 합니다.

사용 가능한 경우 문서화된 이벤트 식별자를 올바른 제공업체 또는 계정 범위 내에서 중복 제거 키로 사용하세요.
식별자가 없다면 안정적인 이벤트 필드로 복합 키를 설계하고 충돌 위험을 테스트하세요.
저장소에서 원자적으로 고유성을 적용하세요. 별도의 ‘확인 후 삽입’ 순서는 동시 전송 중 경쟁 상태를 일으킬 수 있습니다.
후속 작업도 보호하세요. 중복 이벤트가 또 다른 배송 알림을 보내거나 금융 작업을 반복해서는 안 됩니다.
중복 제거 기록을 즉시 삭제하지 말고 제공업체의 재생 동작과 복구 요구사항에 따라 보존 기간을 설정하세요.

시간순 도착을 가정하지 않기

요청이 마지막에 도착했다는 이유만으로 현재 배송 상태를 덮어쓰지 마세요. 이벤트의 의미, 타임스탬프 및 문서화된 순서 정보를 비교하세요. 늦게 도착한 체크포인트는 기록에 보존하되 표시 상태를 자동으로 이전 상태로 되돌리지는 마세요. 동시에 문서화된 정정은 허용해야 합니다. 배송 완료된 배송은 절대 변경될 수 없다는 경직된 규칙은 정당한 예외나 수정된 정보를 숨길 수 있습니다.

실용적인 설정 체크리스트

1. 제공업체 계약 확인

구현 전에 등록 요구사항, 지원 이벤트, 페이로드 형식, 인증, 응답 기대값, 시간 초과, 재시도 동작 및 API 제한을 확인하세요. 알림이 스냅샷인지 증분 변경인지, 전송에 여러 기록이 포함될 수 있는지, 구독 시 초기 상태가 전송되는지 확인하세요.

17TRACK 통합의 경우 공식 Tracking API 페이지와 API 문서에서 시작하세요. 요청 필드와 콜백 요구사항을 정할 때는 제공업체별 문서를 사용하세요. 위의 일반적인 페이로드는 이를 대체하지 않습니다. 배포하려는 통합의 액세스 조건과 운영 제한을 확인하세요.

2. 수신 엔드포인트 보안

HTTPS와 제공업체가 문서화한 인증 메커니즘을 사용하세요. HMAC 서명을 사용하는 경우 지정된 서명 입력값을 정확하게 검증하세요. 원시 요청 바이트에 서명하는 경우 검증 전에 JSON을 파싱하고 다시 직렬화하면 해당 바이트가 변경되어 서명이 무효화될 수 있습니다. 비밀값에서 파생된 서명 값은 일정 시간 비교를 사용하세요.

서명된 타임스탬프나 전송 식별자를 사용할 수 있다면 문서화된 재생 방지 제어를 적용하세요. 유효한 서명은 메시지를 인증하지만 그 자체로 메시지가 최신임을 입증하지는 않습니다. URL과 애플리케이션 로그에 비밀값을 포함하지 말고, 비밀값 교체를 지원하며, 요청 크기를 제한하세요. 관리되는 주소 범위가 있는 경우 IP 허용 목록은 추가 제어 수단이 될 수 있지만 메시지 인증을 대체하지는 않습니다.

3. 수신과 비즈니스 처리 분리

수락된 이벤트를 추적하고 안전하게 재생할 수 있도록 충분한 정보를 저장하세요. 큐 워커는 업데이트를 정규화하고 상태 전환 규칙을 적용하며 작업 결과를 기록해야 합니다. 반복적으로 실패하는 작업은 무한히 재시도하지 말고 검토 가능한 배달 못한 편지 워크플로로 보내세요. 추적 페이로드에는 고객 관련 정보가 포함될 수 있으므로 액세스와 보존 기간을 제한하세요.

4. 출시 전에 장애 경로 테스트

동시 전송을 포함하여 동일한 이벤트를 두 번 전송합니다.
더 최신인 체크포인트 이후에 이전 체크포인트를 전달합니다.
큐 중단과 수신 후 워커 충돌을 시뮬레이션합니다.
잘못된 인증, 잘못된 JSON 및 지나치게 큰 요청을 테스트합니다.
알 수 없는 배송, 누락된 선택 필드 및 추가된 필드를 테스트합니다.
배송 완료된 한 소포가 분할 주문을 완료하지 않도록 확인합니다.
복구 후 이벤트를 재생하고 알림이 계속 중복 제거되는지 확인합니다.

안전한 경우 추가된 필드에는 관대하게 대응하되 알 수 없는 상태 값을 조용히 재해석하지 마세요. 원시 값을 보존하고 인식되지 않은 사례를 정의된 대체 또는 검토 프로세스로 전달하세요.

폴링이 여전히 유용한 경우

폴링은 초기 동기화, 중단 후 복구, 예상된 업데이트가 도착하지 않은 배송 확인에 유용합니다. 그러나 침묵만으로 웹훅 실패를 입증할 수는 없습니다. 소포에 실제로 새로운 스캔이 없을 수도 있습니다. 조용한 모든 배송에 알림이 필요하다고 가정하지 말고 API의 현재 상태 또는 기록과 대조하세요.

규모 계획을 위한 단순화된 폴링 모델은 시간당 요청 수 ≈ 활성 배송 수 × 배송당 시간당 폴링 횟수입니다. 이는 요청당 배송 하나를 가정한 것입니다. 일괄 처리 엔드포인트는 이 계산을 변경합니다. 예를 들어 배송 1,000건을 시간당 네 번 확인하면 재시도 전 기준으로 시간당 4,000개의 요청이 발생합니다. 이는 산술 계산일 뿐 제공업체의 할당량이나 요금 추정치가 아닙니다.

배송 활동과 비즈니스 위험에 따라 확인 일정을 정하고 속도 제한을 준수하며 지터를 추가하여 작업이 모두 동시에 시작되지 않도록 하세요. 재시도 가능한 실패에는 제한된 백오프를 사용하고 적용 가능한 서버 지침을 따르세요. 영구적인 자격 증명 또는 검증 오류는 먼저 수정하지 않은 채 반복해서 재시도하지 마세요.

실용적인 하이브리드 시스템은 일반적인 업데이트에 웹훅을 사용하고 누락이 의심되는 경우 대상 지정 API 조회를 사용합니다. 수신 실패, 큐 대기 시간, 처리 실패, 중복 비율 및 대조 불일치를 별도로 모니터링하세요. 타임스탬프를 신뢰할 수 있는 경우 소스 데이터 지연, 웹훅 전송 지연 및 내부 처리 지연을 구분하세요.

FAQ

추적 웹훅은 실시간인가요?

다음 폴링 주기를 기다리면서 발생하는 지연을 줄일 수 있습니다. 하지만 운송업체의 즉각적인 스캔이나 소스의 즉각적인 업데이트를 보장하지는 않습니다. 엔드투엔드 최신성에는 운송업체 보고, 제공업체 처리, 요청 전송 및 자체 애플리케이션이 포함됩니다.

웹훅을 활성화한 후 폴링을 완전히 중단할 수 있나요?

제공업체의 복구 기능과 비즈니스 요구사항이 이를 허용한다면 가능할 수 있습니다. 운영상 중요한 배송 기록에 대해서는 대조 방법을 유지하세요. 모든 배송을 지속적으로 폴링하는 대신 대상 지정 방식으로 수행할 수 있습니다.

웹훅 엔드포인트가 오프라인이면 어떻게 되나요?

복구는 발신자의 문서화된 재시도 정책에 따라 달라집니다. 재시도가 영구적으로 계속된다고 가정하지 마세요. 엔드포인트를 복구한 후 실패한 전송을 확인하고 지원되는 재전송 도구를 사용하며 가능한 경우 API를 통해 영향을 받은 배송을 대조하세요.

모든 웹훅이 고객 알림을 트리거해야 하나요?

아니요. 이벤트가 중복이거나 과거의 체크포인트일 수 있으며 고객에게 표시되는 상태를 변경하지 않는 업데이트일 수도 있습니다. 예외 및 정정에 대한 규칙을 포함하여 중복 제거된 비즈니스 전환을 기반으로 알림을 트리거하세요.

성공적인 HTTP 응답은 배송 업데이트가 완료되었다는 의미인가요?

반드시 그렇지는 않습니다. 비동기 설계에서 이는 합의된 계약에 따라 수신기가 이벤트를 수락했다는 의미입니다. 수락된 요청이 실패한 워크플로를 숨기지 않도록 처리 완료와 후속 알림 결과를 별도로 추적하세요.

출처

RFC 9110: HTTP Semantics — 처리 수락 및 Retry-After를 포함한 HTTP 응답 의미론.
RFC 2104: HMAC—Keyed-Hashing for Message Authentication — 서명 검증 지침에서 참조하는 HMAC 구성.
GitHub Docs: Best practices for using webhooks — HTTPS, 비밀값, 비동기 처리 및 전송 식별자에 관한 일반적인 엔지니어링 지침입니다. 해당 서비스별 규칙이 배송 제공업체의 동작을 규정하지는 않습니다.
17TRACK Tracking API — 17TRACK 추적 통합을 평가하기 위한 공식 진입점.
17TRACK API documentation — 구현 요구사항에 관한 제공업체별 참조 문서.

17TRACK 배송 추적

AI 기반 DTC 브랜드 주문 추적

17TRACK Order Tracking

17RETURNS

17TRACK API