본문으로 건너뛰기

Tracking Webhook API

Mutation.registerTrackWebhook 를 통해 운송장 상태 변화가 발생하였을때 사용자가 등록한 URL 로 Callback 을 받을 수 있습니다.

기본 절차​

Register & Unregister​

Register​

운송장에 대한 추적을 시작하려면 먼저 Mutation.registerTrackWebhook 를 사용하여 carrierId, trackingNumber, callbackUrl, expirationTime 을 등록하여야 합니다.

팁

carrierId 를 모르시는 경우 먼저 Tracking API 문서를 읽어 봐주세요.

callbackUrl 은 운송장 상태가 변경되었을때 응답을 받고 싶은 사용자의 서버 URL 을 입력해주세요. 딜리버리트래커에서 해당 URL 로 Request 를 전달 합니다.

expirationTime 는 ISO8601 표준을 따르며, 일반적인 경우 현재시간으로부터 48시간 뒤의 시간을 사용하는 것을 권장 합니다. 자세한 내용은 본 문서의 "Webhook Keep Alive"를 참고 해주세요.

Query (GraphQL)
Variables
를 클릭하여 응답을 확인할 수 있습니다.
정보

위의 Try Run 버튼을 통해 테스트 하는 경우 사용자의 프로젝트에 연결되지 않기 때문에 Console 에서 디버깅 할 수 없습니다. 별도의 클라이언트 코드를 작성하여 인증 후 HTTP Request 를 호출하여야 Console 에서 디버깅 할 수 있습니다.

Unregister​

Mutation.registerTrackWebhook 의 expirationTime에 미래 시간이 아닌 현재 시간을 전달하여 명시적으로 Webhook 을 등록해제 할 수 있습니다.

하지만, 이렇게 명시적으로 API를 호출을 호출하여 명시적으로 등록 해제 하는 것보다 TTL 만료를 통해 자동 삭제 시키는 것을 추천합니다. 자세한 내용은 본 문서의 "Webhook Keep Alive" 파트를 참고해주세요.

Implementing a Callback Handler​

딜리버리트래커 Webhook 시스템이 운송장에 변화를 감지하면 등록된 Callback URL 로 다음과 같은 Request 를 전송 합니다.

POST {callbackUrl}
content-type: application/json

{
  "carrierId": "{carrierId}",
  "trackingNumber": "{trackingNumber}"
}

Callback 에는 carrierId 와 trackingNumber 만 전달되며, 이 정보를 기반으로 Query.track 를 사용하여 사용자가 원하는 정보를 조회할 수 있습니다.

대표적인 구현 방법​

상황에 맞게 두가지 구현 방법 중 하나를 선택하여 Callback Handler를 구현 할 수 있습니다.

방법 1. Callback Queue 를 통한 처리​

Callback Handler 내에서 별도의 Queue 에 TrackingNumber 을 넣어두고, 별도의 Worker 에서 Queue에 쌓여진 TrackingNumber를 읽어 Query.track를 호출하는 방법을 권장하고 있습니다.

방법 2. Callback Handler 내에서 Query.track 직접 호출​

Queue 처리가 상황상 어렵다면, Callback Handler 내에서 바로 Query.track 호출 하시는 방법도 존재합니다. 다만, 이러한 방식은 기본 구현은 쉬우나, 트래픽이 많은 경우 구현 방법1에 비해 상대적으로 Timeout 과 RateLimit 에 대한 복잡성을 키울 수 있습니다.

Callback Response Code & Retry​

Callback 구현은 Response 를 1초 내에 전달하고 Response Status Code 로 202 (Accepted) 를 보내실 것을 권장 합니다.

Callback Url 의 HTTP Response Status Code 가 2XX 가 아닌 경우 내부 Exponential Backoff Retry 로직에 따라 expirationTime 도달 전까지 계속하여 재시도 합니다.

팁

계속하여 Callback 에러가 발생하거나 expirationTime가 짧아 expirationTime가 만료되는 상황을 방지하려면 주기적으로 expirationTime 를 갱신하여 주세요. 자세한 내용은 Webhook Keep Alive 를 참고 바랍니다.

Webhook Keep Alive​

추적을 원하는 운송장 번호가 생긴 경우, 현재 시간의 48 시간 뒤의 미래 시간을 expirationTime 으로 사용하고 expirationTime 을 주기적(24시간 마다)으로 갱신하는 것을 권장 합니다.

24 시간에 한번씩 추적을 계속하여야 하는 운송장 번호 목록에 대하여, Mutation.registerTrackWebhook 를 다시 한번 호출(expirationTime를 현재 시간 + 48 시간) 하는 것을 권장 합니다.

이로써 계속 추적 하여야 하는 대상은 계속 expirationTime 이 증가하고, 추적 대상이 아닌 경우 48시간 뒤에 자동으로 등록 해제 할 수 있습니다.

이러한 방식을 사용하여 Register 와 Unregister 의 순서를 잘못 전송하여 의도하지 않게 Unregister 하거나 영원히 Register 상태로 남아 있는 상황을 피할 수 있습니다.

Testing​

실제 운송장에 변화가 발생할때까지 기다리는 것은 상당히 시간(n시간에서 n일)이 소요 됩니다.

팁

Dummy Tracking Number 를 사용하는 방법도 존재 합니다.

이러한 시간을 줄이고자 Delivery Tracker Console 의 프로젝트 내의 "Webhook" 메뉴에서는 등록된 Webhook 목록과 "Callback Call Test Trigger" 버튼을 클릭하여 Callback 호출 Queue 에 Callback 호출 요청을 할 수 있습니다.

이렇게 발생한 Callback 은 일반적으로는 n분 내에 처리되며, 운송장 상태가 변경되지 않더라도 발송 됩니다.

Notes​

Query.track 를 polling 하는 것보다 Track Webhook 을 사용하면 어떤 점이 좋은가요?​

딜리버리 트래커 내부 최적화 로직에 따라 효율적으로 동작하게 설계되어 있습니다.

예로 일반적인 경우 Callback 이 발생한 직후 Query.track를 호출하는 경우 Tracking data 가 캐싱되어 있어 Query.track 를 polling 하여 사용하는 것보다 더 짧은 레이턴시로 사용할 수 있습니다. 또한, polling 주기 등 polling 시에 발생할 수 있는 여러 상황을 신경 쓸 필요 없어지게 되며 Callback 발생시에만 Track API를 호출하여 Track API 호출 빈도를 줄여 Rate Limit 을 효율적으로 사용하실 수 있습니다.

Callback 발생이 보장 되나요?​

expirationTime에 도달하지 않는 한, 운송장 상태가 변경되는 경우 Callback 발생이 보장 됩니다. (첫 초기화 시점에도 Callback 이 발생 합니다.) 내부 Retry 로직에 따라 주기적으로 Retry 합니다.

warning

expirationTime 까지 성공하지 못하는 경우 한번도 발송하지 못하고 삭제될 수 있으니 expirationTime 관리에 유의 해주세요. 자세한 내용은 "Webhook Keep Alive"를 참고 해주세요.

API Rate Limit에 유의 해주세요.​

프로젝트에 주어진 API Call Rate Limit 에 유의하여 주세요.

큐에 넣어서 사용 하세요.​

Callback 내에 track api 호출을 구현하는 것보다는 Callback 에서는 별도의 Queue 에 변경 사실을 전달하고 별도의 Worker 에서 처리하시는 것을 권장 합니다.

상황에 따라 변경이 없어도 이벤트가 발생할 수 있습니다.​

내부 Hash 변경 등 상황에 따라 변경이 없어도 이벤트가 발생할 수 있습니다.

Callback Url 의 동작은 딜리버리 트래커 서버외에 다른 서버에서 Callback Url로 데이터를 조작하여 보낼 수 있다고 가정하고 설계되어야 합니다.​

Callback Url 의 정보만 알면 누구나 호출할 수 있기 때문에 딜리버리 트래커 서버에서 보낸 데이터라는 것을 신뢰할 수 없습니다.

노트

HMAC 등의 인증을 원하는 경우 별도 문의 바랍니다.

Callback 개발시 딜리버리 트래커 Webhook 서버의 IP Address 만을 허용하는 조치를 취하지 마십시오.​

딜리버리 트래커에서 Callback Url 호출에 사용되는 IP Address는 언제든지 변경 될 수 있습니다.