whereparcel

궁금한 게 있으세요? 편하게 물어보세요. WhereParcel을 만든 개발자가 직접 읽고 답장드립니다.

웹훅 API - WhereParcel

택배 추적 업데이트를 웹훅으로 자동 수신. 약 12시간마다 다시 조회해 상태를 푸시합니다. 서명된 페이로드와 언제든 조회할 수 있는 변경 이력 제공.

플레이그라운드에서 테스트 빠른 시작 가이드 → 시작하기 →

EndpointPOST/v2/webhooks/register
웹훅 등록 (과금 대상)

개요

택배 추적을 위한 웹훅을 등록합니다. 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)

201Created — 웹훅 등록 성공
{
  "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)

400Bad Request — 잘못된 요청 — 검증 실패(REQUEST_VALIDATION_FAILED, invalidItems 포함) 또는 잘못된 필드(INVALID_REQUEST)
{
  "success": false,
  "error": {
    "code": "REQUEST_VALIDATION_FAILED",
    "message": "1 invalid item(s) found"
  }
}

오류 응답 (401)

401Unauthorized — 인증 실패
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

오류 응답 (403)

403Forbidden — 거부 — 공개 데모 키는 WhereParcel 플레이그라운드에서만 동작합니다(DEMO_KEY_BROWSER_ONLY). 또는 트라이얼 한도 도달(TRIAL_LIMIT_REACHED)
{
  "success": false,
  "error": {
    "code": "DEMO_KEY_BROWSER_ONLY",
    "message": "This test key only works from the WhereParcel Playground (https://whereparcel.com/playground)."
  }
}

오류 응답 (429)

429Too Many Requests — 요청 한도 · 사용량 초과(RATE_LIMIT_EXCEEDED, MINUTE_QUOTA_EXCEEDED, MONTHLY_QUOTA_EXCEEDED, DEMO_KEY_IP_LIMIT_EXCEEDED)
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  }
}
EndpointGET/v2/webhooks/subscriptions
웹훅 구독 목록 조회

개요

등록한 모든 웹훅 구독(구독형 + 일회성)을 조회합니다. 무료 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)

200OK — 구독 목록 조회 성공
{
  "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)

401Unauthorized — 인증 실패
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
EndpointGET/v2/webhooks/subscriptions/{requestId}
단일 웹훅 구독 조회

개요

특정 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)

200OK — 구독 정보 조회 성공
{
  "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)

401Unauthorized — 인증 실패
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

오류 응답 (403)

403Forbidden — 다른 계정의 구독
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You can only access your own requests"
  }
}

오류 응답 (404)

404Not Found — requestId를 찾을 수 없음
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}
EndpointDELETE/v2/webhooks/subscriptions/{requestId}
웹훅 구독 삭제

개요

웹훅 구독을 취소하고 모니터링을 중지합니다. 구독형(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)

200OK — 구독 삭제 성공
{
  "success": true,
  "data": {
    "deleted": true,
    "requestId": "req_abc123xyz",
    "message": "Webhook subscription deleted successfully"
  }
}

오류 응답 (401)

401Unauthorized — 인증 실패
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

오류 응답 (404)

404Not Found — requestId를 찾을 수 없음
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}
EndpointGET/v2/webhooks/subscriptions/{requestId}/changes
웹훅 변경 이력 조회

개요

특정 웹훅 구독의 모든 변경 이력(배송 상태 변경)을 조회합니다. 무료 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)

200OK — 변경 이력 조회 성공
{
  "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)

401Unauthorized — 인증 실패
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

오류 응답 (403)

403Forbidden — 다른 계정의 구독
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You can only access your own requests"
  }
}

오류 응답 (404)

404Not Found — requestId를 찾을 수 없음
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}
EndpointGET/v2/webhooks/subscriptions/{requestId}/changes/{changeId}
단일 변경 이벤트 조회

개요

특정 변경 이벤트의 상세 정보를 조회합니다. 무료 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)

200OK — 변경 이벤트 조회 성공
{
  "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)

401Unauthorized — 인증 실패
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

오류 응답 (403)

403Forbidden — 다른 계정의 구독
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You can only access your own requests"
  }
}

오류 응답 (404)

404Not Found — requestId 또는 changeId를 찾을 수 없음
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}
EndpointPOST/v2/webhooks/results
웹훅 결과 배치 검색

개요

여러 택배의 웹훅 결과를 한 번에 검색합니다. 등록한 웹훅의 최종 결과를 조회할 때 사용합니다.

검색 방식:

  • 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)

200OK — 배치 검색 성공
{
  "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)

400Bad Request — 잘못된 요청 — trackingItems 가 없거나 비었거나 100개 초과, 또는 (carrier 와 trackingNumber) 나 clientId 가 없는 항목(INVALID_REQUEST)
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "trackingItems array is required and must not be empty"
  }
}

오류 응답 (401)

401Unauthorized — 인증 실패
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}