웹훅 API - WhereParcel
택배 추적 업데이트를 웹훅으로 자동 수신. 약 12시간마다 다시 조회해 상태를 푸시합니다. 서명된 페이로드와 언제든 조회할 수 있는 변경 이력 제공.
개요
택배 추적을 위한 웹훅을 등록합니다. 2가지 모드를 지원합니다:
recurring: true— 배송 완료까지 모니터링 (구독형). 대부분의 연동에 권장됩니다. 한 번 등록하면 약 12시간마다, 최대 10일 동안 다시 조회해 조회할 때마다 결과를 엔드포인트로 보냅니다. DB 동기화에 이상적입니다.recurring: false— 1회만 조회 (일회성, 기본값). 지속적인 업데이트가 필요 없는 단발 조회에 적합합니다.
왜 웹훅을 사용해야 하나요? /v2/track을 반복 폴링하면 요청 한도를 낭비합니다. 웹훅을 사용하면 택배 1건은 등록할 때 한 번만 차감되고, 이후 조회는 모두 무료입니다.
과금 대상 API이며, 최대 100건까지 한 번에 등록 가능합니다.
저희가 고객님 엔드포인트로 POST 하는 내용입니다. Content-Type 은 application/json 이며, 10초 안에 2xx 응답을 기대합니다. 리다이렉트는 따라가지 않습니다. 발송은 한 번만 시도하며 재시도하지 않습니다 — 장애 뒤에는 GET /v2/webhooks/subscriptions/{requestId}/changes 로 놓친 변경을 확인하세요.
{
"event": "tracking.updated",
"timestamp": "2026-08-21T04:15:22.184Z",
"data": {
"requestId": "req_abc123",
"timestamp": "2026-08-21T04:15:22.100Z",
"trackingItems": [
{
"carrier": { "code": "us.usps", "name": "USPS", "country": "US" },
"trackingNumber": "9400111206206406260787",
"status": "success",
"currentStatus": "in_transit",
"hasChange": true,
"trackingData": { "deliveryStatus": "in_transit", "events": [] }
}
],
"isPeriodicUpdate": true,
"hasChanges": true,
"changedItemCount": 1,
"queriedItemCount": 1,
"deliveredItemCount": 0,
"changeId": "chg_xyz789"
}
}
필드 설명:
event — 등록 직후 최초 조회는 tracking.registered, 이후 갱신 조회(약 12시간마다)는 tracking.updated.
data.requestId — 이 엔드포인트가 반환한 구독 ID.
data.trackingItems[] — 추적 항목당 1개. carrier 는 문자열이 아니라 객체(code·name·country)입니다. status 는 success 또는 failed 입니다 — failed 는 조회 자체가 실패했다는 뜻이며(택배사 사이트 차단·접속 불가), 그 항목에는 마지막으로 알려진 trackingData 와 함께 error 객체가 실립니다. 동기조회 POST /v2/track 응답은 같은 상황을 error 로 보고하므로 값이 다릅니다 — 여기서는 failed 로 판정하세요. currentStatus 는 표준화된 배송 상태, trackingData 는 전체 결과, hasChange 는 이번 주기에 상태가 바뀐 항목 표시.
data.isPeriodicUpdate·hasChanges·changedItemCount·queriedItemCount·deliveredItemCount — 구독 갱신 시에만 포함되며 최초 tracking.registered 발송에는 없습니다. changeId 와 그 별칭 changeEventId 는 실제로 변경이 있었던 주기(changedItemCount > 0)에만 포함되며, 두 값은 같고 GET /v2/webhooks/subscriptions/{requestId}/changes/{changeId} 로 조회할 변경 기록을 가리킵니다.
헤더: X-WhereParcel-Event, X-WhereParcel-Timestamp, X-WhereParcel-Signature. 서명은 엔드포인트 시크릿을 키로 원본 JSON 본문 그대로에 대해 계산한 HMAC-SHA256 hex 다이제스트입니다. 파싱 전 원본 본문으로 다시 계산해 대조하세요.
webhookEndpointId 없이 등록하면 아무것도 발송되지 않습니다. 이 경우가 pull 모드이며 GET /v2/webhooks/subscriptions/{requestId} 또는 POST /v2/webhooks/results 로 결과를 가져오세요. 위 페이로드를 받으려면 POST /v2/webhook-endpoints 로 엔드포인트를 만들고 그 ID 를 webhookEndpointId 로 넘기시면 됩니다.
요청 예제
// npm install whereparcel
import { WhereParcel } from 'whereparcel';
const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');
const result = await wp.registerWebhook({
"trackingItems": [
{
"carrier": "kr.cj",
"trackingNumber": "123456789012",
"clientId": "order-001"
},
{
"carrier": "de.gls",
"trackingNumber": "48117308687",
"postalCode": "04179",
"clientId": "order-002"
}
],
"recurring": true,
"webhookEndpointId": "wep_a1b2c3d4e5f6"
});
console.log(result); curl -X POST https://api.whereparcel.com/v2/webhooks/register \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"trackingItems": [
{
"carrier": "kr.cj",
"trackingNumber": "123456789012",
"clientId": "order-001"
},
{
"carrier": "de.gls",
"trackingNumber": "48117308687",
"postalCode": "04179",
"clientId": "order-002"
}
],
"recurring": true,
"webhookEndpointId": "wep_a1b2c3d4e5f6"
}' const response = await fetch('https://api.whereparcel.com/v2/webhooks/register', {
method: 'POST',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
"trackingItems": [
{
"carrier": "kr.cj",
"trackingNumber": "123456789012",
"clientId": "order-001"
},
{
"carrier": "de.gls",
"trackingNumber": "48117308687",
"postalCode": "04179",
"clientId": "order-002"
}
],
"recurring": true,
"webhookEndpointId": "wep_a1b2c3d4e5f6"
})
});
const data = await response.json();
console.log(data); <?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhooks/register');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
$headers = [
'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$data = [
'trackingItems' => [
[
'carrier' => "kr.cj",
'trackingNumber' => "123456789012",
'clientId' => "order-001"
],
[
'carrier' => "de.gls",
'trackingNumber' => "48117308687",
'postalCode' => "04179",
'clientId' => "order-002"
]
],
'recurring' => true,
'webhookEndpointId' => "wep_a1b2c3d4e5f6"
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
print_r($result); import requests
url = 'https://api.whereparcel.com/v2/webhooks/register'
headers = {
'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type': 'application/json'
}
data = {
'trackingItems': [
{
'carrier': "kr.cj",
'trackingNumber': "123456789012",
'clientId': "order-001"
},
{
'carrier': "de.gls",
'trackingNumber': "48117308687",
'postalCode': "04179",
'clientId': "order-002"
}
],
'recurring': True,
'webhookEndpointId': "wep_a1b2c3d4e5f6"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result) package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.whereparcel.com/v2/webhooks/register"
payload := []byte(`{"trackingItems":[{"carrier":"kr.cj","trackingNumber":"123456789012","clientId":"order-001"},{"carrier":"de.gls","trackingNumber":"48117308687","postalCode":"04179","clientId":"order-002"}],"recurring":true,"webhookEndpointId":"wep_a1b2c3d4e5f6"}`)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
} 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.
요청 본문
trackingItems array · required | 추적 항목 (최대 100개) |
trackingItems[].carrier string · required | |
trackingItems[].trackingNumber string · required | |
trackingItems[].clientId string | |
trackingItems[].postalCode string | |
trackingItems[].phoneNumber string | |
recurring boolean | ⭐ 추적 모드 (선택적, 기본값: false) - false: 1회만 조회 (기본값, 안전함) → webhookEndpointId 선택적 - true: 계속 모니터링 (명시적 요청 필요) → webhookEndpointId 필수 |
webhookEndpointId string | 사전 등록된 Webhook Endpoint ID - recurring: true일 때 필수 (미들웨어 검증) - recurring: false일 때 선택적 - 있으면 완료 시 POST 전송, 없으면 전송 안함 - 먼저 Webhook Endpoint를 등록해야 함 |
응답
성공 응답 (201)
{
"success": true,
"data": {
"requestId": "req_abc123xyz",
"recurring": true,
"trackingItemCount": 2,
"webhookEndpointId": "wep_a1b2c3d4e5f6",
"message": "Tracking registered. Updates will be delivered to your webhook endpoint until delivery."
}
} 오류 응답 (400)
{
"success": false,
"error": {
"code": "REQUEST_VALIDATION_FAILED",
"message": "1 invalid item(s) found"
}
} 오류 응답 (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} 오류 응답 (403)
{
"success": false,
"error": {
"code": "DEMO_KEY_BROWSER_ONLY",
"message": "This test key only works from the WhereParcel Playground (https://whereparcel.com/playground)."
}
} 오류 응답 (429)
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Please try again later."
}
} 개요
등록한 모든 웹훅 구독(구독형 + 일회성)을 조회합니다. 무료 API로 사용량이 차감되지 않습니다.
요청 예제
// npm install whereparcel
import { WhereParcel } from 'whereparcel';
const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');
const subscriptions = await wp.getSubscriptions();
console.log(subscriptions); curl -X GET https://api.whereparcel.com/v2/webhooks/subscriptions \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \ -H "Content-Type: application/json"
const response = await fetch('https://api.whereparcel.com/v2/webhooks/subscriptions', {
method: 'GET',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data); <?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhooks/subscriptions'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET'); $headers = [ 'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY', 'Content-Type: application/json' ]; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); print_r($result);
import requests
url = 'https://api.whereparcel.com/v2/webhooks/subscriptions'
headers = {
'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
result = response.json()
print(result) package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.whereparcel.com/v2/webhooks/subscriptions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
} 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.
응답
성공 응답 (200)
{
"success": true,
"data": [
{
"requestId": "req_abc123xyz",
"trackingItemCount": 2,
"trackingItems": [
{
"carrier": "kr.cj",
"trackingNumber": "300718039335",
"clientId": "order-001",
"latestStatus": "delivered"
},
{
"carrier": "kr.lotte",
"trackingNumber": "410259694563",
"latestStatus": "in_transit"
}
],
"recurring": true,
"webhookEndpointId": "wep_a1b2c3d4e5f6",
"isActive": true,
"createdAt": "2026-02-05T10:00:00.000Z",
"updatedAt": "2026-02-05T14:30:00.000Z"
},
{
"requestId": "req_def456uvw",
"trackingItemCount": 1,
"trackingItems": [
{
"carrier": "kr.post",
"trackingNumber": "1234567890123",
"latestStatus": "out_for_delivery"
}
],
"recurring": false,
"isActive": false,
"progress": {
"total": 1,
"completed": 1,
"succeeded": 1,
"failed": 0,
"percentage": 100
},
"createdAt": "2026-02-04T09:00:00.000Z",
"updatedAt": "2026-02-04T09:05:00.000Z",
"completedAt": "2026-02-04T09:05:00.000Z"
}
]
} 오류 응답 (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} 개요
특정 requestId의 웹훅 구독 정보를 조회합니다. 무료 API로 사용량이 차감되지 않습니다.
요청 예제
// npm install whereparcel
import { WhereParcel } from 'whereparcel';
const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');
const subscription = await wp.getSubscription('req_abc123xyz');
console.log(subscription); curl -X GET https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \ -H "Content-Type: application/json"
const response = await fetch('https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz', {
method: 'GET',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data); <?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET'); $headers = [ 'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY', 'Content-Type: application/json' ]; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); print_r($result);
import requests
url = 'https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz'
headers = {
'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
result = response.json()
print(result) package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
} 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.
경로 매개변수
requestId string · required | <p>웹훅 등록 시 받은 requestId</p>
req_abc123xyz |
응답
성공 응답 (200)
{
"success": true,
"data": {
"requestId": "req_abc123xyz",
"trackingItemCount": 2,
"trackingItems": [
{
"carrier": "kr.cj",
"trackingNumber": "300718039335",
"clientId": "order-001",
"latestStatus": "delivered"
},
{
"carrier": "kr.lotte",
"trackingNumber": "410259694563",
"latestStatus": "in_transit"
}
],
"recurring": true,
"webhookEndpointId": "wep_a1b2c3d4e5f6",
"isActive": true,
"createdAt": "2026-02-05T10:00:00.000Z",
"updatedAt": "2026-02-05T14:30:00.000Z"
}
} 오류 응답 (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} 오류 응답 (403)
{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You can only access your own requests"
}
} 오류 응답 (404)
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found"
}
} 개요
웹훅 구독을 취소하고 모니터링을 중지합니다. 구독형(recurring) 웹훅의 경우 즉시 중지됩니다. 무료 API로 사용량이 차감되지 않습니다.
요청 예제
// npm install whereparcel
import { WhereParcel } from 'whereparcel';
const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');
const result = await wp.deleteSubscription('req_abc123xyz');
console.log(result); curl -X DELETE https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \ -H "Content-Type: application/json"
const response = await fetch('https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz', {
method: 'DELETE',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data); <?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE'); $headers = [ 'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY', 'Content-Type: application/json' ]; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); print_r($result);
import requests
url = 'https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz'
headers = {
'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type': 'application/json'
}
response = requests.delete(url, headers=headers)
result = response.json()
print(result) package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
} 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.
경로 매개변수
requestId string · required | <p>삭제할 웹훅의 requestId</p>
req_abc123xyz |
응답
성공 응답 (200)
{
"success": true,
"data": {
"deleted": true,
"requestId": "req_abc123xyz",
"message": "Webhook subscription deleted successfully"
}
} 오류 응답 (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} 오류 응답 (404)
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found"
}
} 개요
특정 웹훅 구독의 모든 변경 이력(배송 상태 변경)을 조회합니다. 무료 API로 사용량이 차감되지 않습니다.
요청 예제
// npm install whereparcel — this endpoint has no SDK method yet, so plain fetch:
const response = await fetch('https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes', {
method: 'GET',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data); curl -X GET https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \ -H "Content-Type: application/json"
const response = await fetch('https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes', {
method: 'GET',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data); <?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET'); $headers = [ 'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY', 'Content-Type: application/json' ]; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); print_r($result);
import requests
url = 'https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes'
headers = {
'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
result = response.json()
print(result) package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
} 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.
경로 매개변수
requestId string · required | <p>웹훅 등록 시 받은 requestId</p>
req_abc123xyz |
쿼리 매개변수
limit integer | <p>반환할 최대 건수 (기본 20, 최대 100). 최신순 정렬.</p> |
응답
성공 응답 (200)
{
"success": true,
"data": {
"requestId": "req_abc123xyz",
"changes": [
{
"changeId": "change_1770282900000",
"timestamp": "2026-02-05T09:15:00.000Z",
"changedItemCount": 1,
"preview": {
"trackingNumbers": [
"300718039335"
]
}
},
{
"changeId": "change_1770301800000",
"timestamp": "2026-02-05T14:30:00.000Z",
"changedItemCount": 2,
"preview": {
"trackingNumbers": [
"300718039335",
"300718039336"
]
}
}
],
"pagination": {
"limit": 20,
"hasMore": false
}
}
} 오류 응답 (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} 오류 응답 (403)
{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You can only access your own requests"
}
} 오류 응답 (404)
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found"
}
} 개요
특정 변경 이벤트의 상세 정보를 조회합니다. 무료 API로 사용량이 차감되지 않습니다.
요청 예제
// npm install whereparcel — this endpoint has no SDK method yet, so plain fetch:
const response = await fetch('https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes/change_def456', {
method: 'GET',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data); curl -X GET https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes/change_def456 \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \ -H "Content-Type: application/json"
const response = await fetch('https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes/change_def456', {
method: 'GET',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data); <?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes/change_def456'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET'); $headers = [ 'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY', 'Content-Type: application/json' ]; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); print_r($result);
import requests
url = 'https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes/change_def456'
headers = {
'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
result = response.json()
print(result) package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.whereparcel.com/v2/webhooks/subscriptions/req_abc123xyz/changes/change_def456"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
} 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.
경로 매개변수
requestId string · required | <p>웹훅 등록 시 받은 requestId</p>
req_abc123xyz |
changeId string · required | <p>변경 이벤트 ID</p>
change_def456 |
응답
성공 응답 (200)
{
"success": true,
"data": {
"changeId": "change_1770282900000",
"requestId": "req_abc123xyz",
"timestamp": "2026-02-05T09:15:00.000Z",
"changedItemCount": 1,
"changedItems": [
{
"carrier": "kr.cj",
"trackingNumber": "300718039335",
"previousStatus": "in_transit",
"currentStatus": "out_for_delivery",
"trackingData": {
"deliveryStatus": "out_for_delivery",
"lastUpdated": "2026-02-05T09:15:00.000Z",
"events": [
{
"timestamp": "2026-02-05T08:00:00+09:00",
"status": "in_transit",
"location": "서울 송파구 센터",
"description": "배송 중"
},
{
"timestamp": "2026-02-05T09:15:00+09:00",
"status": "out_for_delivery",
"location": "서울 강남구 센터",
"description": "배달 출발"
}
]
}
}
]
}
} 오류 응답 (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} 오류 응답 (403)
{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You can only access your own requests"
}
} 오류 응답 (404)
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found"
}
} 개요
여러 택배의 웹훅 결과를 한 번에 검색합니다. 등록한 웹훅의 최종 결과를 조회할 때 사용합니다.
검색 방식:
- carrier + trackingNumber로 검색
- clientId로 검색
- 두 방식을 동시에 사용 가능
동작 방식:
- tracking_requests 컬렉션에서 trackingIndex/clientIdIndex 필드를 사용하여 검색
- 같은 송장번호가 여러 문서에 있을 경우 최신 문서만 반환
- Firestore array-contains-any 제한(10개)으로 인해 배치 처리 (최대 100개 조회 시 10번 쿼리)
무료 API로 사용량이 차감되지 않습니다.
요청 예제
// npm install whereparcel — this endpoint has no SDK method yet, so plain fetch:
const response = await fetch('https://api.whereparcel.com/v2/webhooks/results', {
method: 'POST',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
"trackingItems": [
{
"carrier": "kr.cj",
"trackingNumber": "300718039335"
},
{
"carrier": "de.gls",
"trackingNumber": "48117308687",
"postalCode": "04179"
}
]
})
});
const data = await response.json();
console.log(data); curl -X POST https://api.whereparcel.com/v2/webhooks/results \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"trackingItems": [
{
"carrier": "kr.cj",
"trackingNumber": "300718039335"
},
{
"carrier": "de.gls",
"trackingNumber": "48117308687",
"postalCode": "04179"
}
]
}' const response = await fetch('https://api.whereparcel.com/v2/webhooks/results', {
method: 'POST',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
"trackingItems": [
{
"carrier": "kr.cj",
"trackingNumber": "300718039335"
},
{
"carrier": "de.gls",
"trackingNumber": "48117308687",
"postalCode": "04179"
}
]
})
});
const data = await response.json();
console.log(data); <?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/webhooks/results');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
$headers = [
'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$data = [
'trackingItems' => [
[
'carrier' => "kr.cj",
'trackingNumber' => "300718039335"
],
[
'carrier' => "de.gls",
'trackingNumber' => "48117308687",
'postalCode' => "04179"
]
]
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
print_r($result); import requests
url = 'https://api.whereparcel.com/v2/webhooks/results'
headers = {
'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type': 'application/json'
}
data = {
'trackingItems': [
{
'carrier': "kr.cj",
'trackingNumber': "300718039335"
},
{
'carrier': "de.gls",
'trackingNumber': "48117308687",
'postalCode': "04179"
}
]
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result) package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.whereparcel.com/v2/webhooks/results"
payload := []byte(`{"trackingItems":[{"carrier":"kr.cj","trackingNumber":"300718039335"},{"carrier":"de.gls","trackingNumber":"48117308687","postalCode":"04179"}]}`)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
} 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.
요청 본문
trackingItems array · required |
응답
성공 응답 (200)
{
"success": true,
"data": {
"results": {
"us.fedex:231300687629630": {
"source": "webhook",
"data": {
"deliveryStatus": "delivered",
"events": [
{
"timestamp": "2026-02-05T09:15:00-05:00",
"status": "out_for_delivery",
"location": "Brooklyn, NY",
"description": "On FedEx vehicle for delivery"
},
{
"timestamp": "2026-02-05T14:30:00-05:00",
"status": "delivered",
"location": "New York, NY",
"description": "Delivered, left at front door"
}
],
"lastUpdated": "2026-02-05T14:30:00-05:00"
},
"status": "delivered",
"requestId": "req_abc123xyz",
"createdAt": "2026-02-05T10:00:00.000Z"
},
"clientId:order-002": {
"source": "webhook",
"data": [
{
"carrier": "us.usps",
"trackingNumber": "9400111899562537866361",
"clientId": "order-002",
"status": "in_transit",
"data": {
"deliveryStatus": "in_transit",
"events": [
{
"timestamp": "2026-02-05T12:00:00-05:00",
"status": "in_transit",
"location": "Chicago, IL",
"description": "In transit to next facility"
}
],
"lastUpdated": "2026-02-05T12:00:00-05:00"
}
}
],
"requestId": "req_def456uvw",
"createdAt": "2026-02-05T10:00:00.000Z"
},
"us.ups:1Z999AA10123456784": {
"source": "none",
"data": null,
"status": null
}
}
}
} 오류 응답 (400)
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "trackingItems array is required and must not be empty"
}
} 오류 응답 (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}