Webhooks API — Tracking Push Notifications
Subscribe to shipment tracking updates via webhooks. We re-check each parcel about every 12 hours and push the status to you, with signed payloads and a change history you can query anytime.
Overview
Register a webhook for parcel tracking. Supports 2 modes:
recurring: true— Monitoring until delivery (subscription). Recommended for most integrations. Register once and we re-check the parcel about every 12 hours, for up to 10 days, and push the result to your endpoint after every check. Ideal for keeping your database in sync with delivery progress.recurring: false— Query once only (one-time, default). Useful for one-off lookups where you don't need ongoing updates.
Why use webhooks? Polling /v2/track repeatedly wastes your request quota. With webhooks, a parcel counts once when you register it, and every check after that is free.
Billable API, supports up to 100 items per registration.
What we POST to your endpoint. Content-Type is application/json; we expect a 2xx response within 10 seconds. Redirects are not followed. Each delivery is attempted once and is not retried — after downtime, catch up with 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"
}
}
Fields:
event — tracking.registered on the first lookup after you register, tracking.updated on every later check (about every 12 hours).
data.requestId — the subscription id returned by this endpoint.
data.trackingItems[] — one entry per tracked parcel. carrier is an object (code, name, country), not a string. status is success or failed — failed means the lookup itself did not succeed (carrier site blocked or unreachable); such an item still carries the last known trackingData, plus an error object. Note the difference from the synchronous POST /v2/track response, where the same condition is reported as error. Match on failed here. currentStatus is the standardized delivery status. trackingData holds the full result. hasChange marks items whose status changed in this cycle.
data.isPeriodicUpdate, hasChanges, changedItemCount, queriedItemCount, deliveredItemCount — present only on recurring updates, not on the first tracking.registered delivery. changeId and its alias changeEventId are present only on cycles that actually had a change (changedItemCount > 0); both carry the same value and identify the record retrievable via GET /v2/webhooks/subscriptions/{requestId}/changes/{changeId}.
Headers: X-WhereParcel-Event, X-WhereParcel-Timestamp, and X-WhereParcel-Signature — an HMAC-SHA256 hex digest of the exact raw JSON body, keyed with your endpoint secret. Verify it by recomputing the digest over the raw body before parsing.
If you register without webhookEndpointId, nothing is pushed to you. That is the pull mode: retrieve results with GET /v2/webhooks/subscriptions/{requestId} or POST /v2/webhooks/results. To receive the payload above, create an endpoint with POST /v2/webhook-endpoints and pass its id as webhookEndpointId.
Example Request
// npm install whereparcel
import { WhereParcel } from 'whereparcel';
const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');
const result = await wp.registerWebhook({
"trackingItems": [
{
"carrier": "us.fedex",
"trackingNumber": "123456789012",
"clientId": "order-001"
},
{
"carrier": "us.fedex",
"trackingNumber": "612938472651",
"postalCode": "10001",
"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": "us.fedex",
"trackingNumber": "123456789012",
"clientId": "order-001"
},
{
"carrier": "us.fedex",
"trackingNumber": "612938472651",
"postalCode": "10001",
"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": "us.fedex",
"trackingNumber": "123456789012",
"clientId": "order-001"
},
{
"carrier": "us.fedex",
"trackingNumber": "612938472651",
"postalCode": "10001",
"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' => "us.fedex",
'trackingNumber' => "123456789012",
'clientId' => "order-001"
],
[
'carrier' => "us.fedex",
'trackingNumber' => "612938472651",
'postalCode' => "10001",
'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': "us.fedex",
'trackingNumber': "123456789012",
'clientId': "order-001"
},
{
'carrier': "us.fedex",
'trackingNumber': "612938472651",
'postalCode': "10001",
'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":"us.fedex","trackingNumber":"123456789012","clientId":"order-001"},{"carrier":"us.fedex","trackingNumber":"612938472651","postalCode":"10001","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))
} Replace the test API key with your actual API key from the dashboard.
Request Body
trackingItems array · required | Tracking items (up to 100) |
trackingItems[].carrier string · required | |
trackingItems[].trackingNumber string · required | |
trackingItems[].clientId string | |
trackingItems[].postalCode string | |
trackingItems[].phoneNumber string | |
recurring boolean | Tracking mode (optional, default: false) - false: Query once only (default, safe) → webhookEndpointId optional - true: Continuous monitoring (explicit request required) → webhookEndpointId required |
webhookEndpointId string | Pre-registered Webhook Endpoint ID - Required when recurring: true (validated by middleware) - Optional when recurring: false - If provided, sends POST on completion; if omitted, no notification sent - Must register a Webhook Endpoint first |
Response
Success Response (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."
}
} Error Response (400)
{
"success": false,
"error": {
"code": "REQUEST_VALIDATION_FAILED",
"message": "1 invalid item(s) found"
}
} Error Response (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} Error Response (403)
{
"success": false,
"error": {
"code": "DEMO_KEY_BROWSER_ONLY",
"message": "This test key only works from the WhereParcel Playground (https://whereparcel.com/playground)."
}
} Error Response (429)
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Please try again later."
}
} Overview
Retrieve all registered webhook subscriptions (recurring + one-time). Free API - does not count towards usage quota.
Example Request
// 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))
} Replace the test API key with your actual API key from the dashboard.
Response
Success Response (200)
{
"success": true,
"data": [
{
"requestId": "req_abc123xyz",
"trackingItemCount": 2,
"trackingItems": [
{
"carrier": "us.fedex",
"trackingNumber": "300718039335",
"clientId": "order-001",
"latestStatus": "delivered"
},
{
"carrier": "us.usps",
"trackingNumber": "9400111899223197428491",
"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": "us.usps",
"trackingNumber": "9400111899223197428492",
"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"
}
]
} Error Response (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} Overview
Retrieve webhook subscription information for a specific requestId. Free API - does not count towards usage quota.
Example Request
// 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))
} Replace the test API key with your actual API key from the dashboard.
Path Parameters
requestId string · required | <p>requestId received during webhook registration</p>
req_abc123xyz |
Response
Success Response (200)
{
"success": true,
"data": {
"requestId": "req_abc123xyz",
"trackingItemCount": 2,
"trackingItems": [
{
"carrier": "us.fedex",
"trackingNumber": "300718039335",
"clientId": "order-001",
"latestStatus": "delivered"
},
{
"carrier": "us.usps",
"trackingNumber": "9400111899223197428491",
"latestStatus": "in_transit"
}
],
"recurring": true,
"webhookEndpointId": "wep_a1b2c3d4e5f6",
"isActive": true,
"createdAt": "2026-02-05T10:00:00.000Z",
"updatedAt": "2026-02-05T14:30:00.000Z"
}
} Error Response (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} Error Response (403)
{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You can only access your own requests"
}
} Error Response (404)
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found"
}
} Overview
Cancel a webhook subscription and stop monitoring. For recurring webhooks, monitoring stops immediately. Free API - does not count towards usage quota.
Example Request
// 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))
} Replace the test API key with your actual API key from the dashboard.
Path Parameters
requestId string · required | <p>requestId of the webhook to delete</p>
req_abc123xyz |
Response
Success Response (200)
{
"success": true,
"data": {
"deleted": true,
"requestId": "req_abc123xyz",
"message": "Webhook subscription deleted successfully"
}
} Error Response (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} Error Response (404)
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found"
}
} Overview
Retrieve all change history (delivery status changes) for a specific webhook subscription. Free API - does not count towards usage quota.
Example Request
// 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))
} Replace the test API key with your actual API key from the dashboard.
Path Parameters
requestId string · required | <p>requestId received during webhook registration</p>
req_abc123xyz |
Query Parameters
limit integer | <p>Maximum number of records to return (default 20, max 100). Newest first.</p> |
Response
Success Response (200)
{
"success": true,
"data": {
"requestId": "req_abc123xyz",
"changes": [
{
"changeId": "change_1770282900000",
"timestamp": "2026-02-05T09:15:00.000Z",
"changedItemCount": 1,
"preview": {
"trackingNumbers": [
"1Z999AA10123456784"
]
}
},
{
"changeId": "change_1770301800000",
"timestamp": "2026-02-05T14:30:00.000Z",
"changedItemCount": 2,
"preview": {
"trackingNumbers": [
"1Z999AA10123456784",
"1Z999AA10123456785"
]
}
}
],
"pagination": {
"limit": 20,
"hasMore": false
}
}
} Error Response (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} Error Response (403)
{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You can only access your own requests"
}
} Error Response (404)
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found"
}
} Overview
Retrieve detailed information for a specific change event. Free API - does not count towards usage quota.
Example Request
// 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))
} Replace the test API key with your actual API key from the dashboard.
Path Parameters
requestId string · required | <p>requestId received during webhook registration</p>
req_abc123xyz |
changeId string · required | <p>Change event ID</p>
change_def456 |
Response
Success Response (200)
{
"success": true,
"data": {
"changeId": "change_1770282900000",
"requestId": "req_abc123xyz",
"timestamp": "2026-02-05T09:15:00.000Z",
"changedItemCount": 1,
"changedItems": [
{
"carrier": "us.ups",
"trackingNumber": "1Z999AA10123456784",
"previousStatus": "in_transit",
"currentStatus": "out_for_delivery",
"trackingData": {
"deliveryStatus": "out_for_delivery",
"lastUpdated": "2026-02-05T09:15:00.000Z",
"events": [
{
"timestamp": "2026-02-05T03:00:00-05:00",
"status": "in_transit",
"location": "Newark, NJ",
"description": "In transit"
},
{
"timestamp": "2026-02-05T04:15:00-05:00",
"status": "out_for_delivery",
"location": "New York, NY",
"description": "Out for delivery"
}
]
}
}
]
}
} Error Response (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} Error Response (403)
{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You can only access your own requests"
}
} Error Response (404)
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found"
}
} Overview
Search webhook results for multiple parcels at once. Use this to retrieve final results of registered webhooks.
Search methods:
- Search by carrier + trackingNumber
- Search by clientId
- Both methods can be used simultaneously
How it works:
- Searches using trackingIndex/clientIdIndex fields in the tracking_requests collection
- Returns only the latest document when multiple documents exist for the same tracking number
- Batch processed due to Firestore array-contains-any limit (10) (up to 10 queries for 100 items)
Free API - does not count towards usage quota.
Example Request
// 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": "us.fedex",
"trackingNumber": "300718039335"
},
{
"carrier": "us.fedex",
"trackingNumber": "612938472651",
"postalCode": "10001"
}
]
})
});
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": "us.fedex",
"trackingNumber": "300718039335"
},
{
"carrier": "us.fedex",
"trackingNumber": "612938472651",
"postalCode": "10001"
}
]
}' 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": "us.fedex",
"trackingNumber": "300718039335"
},
{
"carrier": "us.fedex",
"trackingNumber": "612938472651",
"postalCode": "10001"
}
]
})
});
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' => "us.fedex",
'trackingNumber' => "300718039335"
],
[
'carrier' => "us.fedex",
'trackingNumber' => "612938472651",
'postalCode' => "10001"
]
]
];
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': "us.fedex",
'trackingNumber': "300718039335"
},
{
'carrier': "us.fedex",
'trackingNumber': "612938472651",
'postalCode': "10001"
}
]
}
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":"us.fedex","trackingNumber":"300718039335"},{"carrier":"us.fedex","trackingNumber":"612938472651","postalCode":"10001"}]}`)
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))
} Replace the test API key with your actual API key from the dashboard.
Request Body
trackingItems array · required |
Response
Success Response (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
}
}
}
} Error Response (400)
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "trackingItems array is required and must not be empty"
}
} Error Response (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}