whereparcel

Stuck on integration? Have a question? The developer is standing by.

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.

Try it in Playground Quick Start Guide → Get Started →

EndpointPOST/v2/webhooks/register
Register webhook (billable)

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)

201Created — Webhook registered successfully
{
  "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)

400Bad Request — Invalid request — validation failed (REQUEST_VALIDATION_FAILED with invalidItems) or invalid fields (INVALID_REQUEST)
{
  "success": false,
  "error": {
    "code": "REQUEST_VALIDATION_FAILED",
    "message": "1 invalid item(s) found"
  }
}

Error Response (401)

401Unauthorized — Authentication failed
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Error Response (403)

403Forbidden — Forbidden — the public demo key works only from the WhereParcel Playground (DEMO_KEY_BROWSER_ONLY), or the trial limit is reached (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)."
  }
}

Error Response (429)

429Too Many Requests — Rate limit or quota exceeded (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
List webhook subscriptions

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)

200OK — Subscription list retrieved successfully
{
  "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)

401Unauthorized — Authentication failed
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
EndpointGET/v2/webhooks/subscriptions/{requestId}
Get webhook subscription

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)

200OK — Subscription info retrieved successfully
{
  "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)

401Unauthorized — Authentication failed
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Error Response (403)

403Forbidden — The subscription belongs to another account
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You can only access your own requests"
  }
}

Error Response (404)

404Not Found — requestId not found
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}
EndpointDELETE/v2/webhooks/subscriptions/{requestId}
Delete webhook subscription

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)

200OK — Subscription deleted successfully
{
  "success": true,
  "data": {
    "deleted": true,
    "requestId": "req_abc123xyz",
    "message": "Webhook subscription deleted successfully"
  }
}

Error Response (401)

401Unauthorized — Authentication failed
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Error Response (404)

404Not Found — requestId not found
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}
EndpointGET/v2/webhooks/subscriptions/{requestId}/changes
List webhook change history

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)

200OK — Change history retrieved successfully
{
  "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)

401Unauthorized — Authentication failed
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Error Response (403)

403Forbidden — The subscription belongs to another account
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You can only access your own requests"
  }
}

Error Response (404)

404Not Found — requestId not found
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}
EndpointGET/v2/webhooks/subscriptions/{requestId}/changes/{changeId}
Get single change event

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)

200OK — Change event retrieved successfully
{
  "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)

401Unauthorized — Authentication failed
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Error Response (403)

403Forbidden — The subscription belongs to another account
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You can only access your own requests"
  }
}

Error Response (404)

404Not Found — requestId or changeId not found
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}
EndpointPOST/v2/webhooks/results
Batch search webhook results

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)

200OK — Batch search completed successfully
{
  "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)

400Bad Request — Bad request — trackingItems missing, empty, over 100, or an item without (carrier and trackingNumber) or clientId (INVALID_REQUEST)
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "trackingItems array is required and must not be empty"
  }
}

Error Response (401)

401Unauthorized — Authentication failed
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}