API reference

Webhooks

Register and list subscriptions in the sandbox; no delivery is sent. Event payloads and signing helpers are available for verification tests. Live dispatch and subscription lifecycle remain launch gaps.

Local sandbox only

Set PX_BASE_URL to http://127.0.0.1:4010/v1. Intended live host: https://api.parcelxpert.com/v1. Live requests are not released. Set PX_IDEMPOTENCY_KEY to one stored unique value per write; replace all example quote and shipment IDs with returned IDs.

Register webhook endpoint

POST/v1/webhook-endpoints

Sandbox registration validates public HTTPS URL shape and returns a signing secret once. It queues fixture events but never sends network traffic. Live subscriptions require encrypted secrets, SSRF checks, durable outbox and worker. Replaying the same registration returns the original response, including its secret: protect idempotency storage. Production access remains disabled. Unreleased server adapters and database controls are under certification; hosted test credentials are unavailable.

Required scope: webhooks:write

Parameters

Name	Location	Meaning
Idempotency-Key required	header	8–128 ASCII letters, digits, underscore, dot, colon or hyphen. Account/environment/operation scoped; never reuse for a different request. Sandbox retains keys until reset.

Request body

Field	Type	Description
`url` required	string	Public HTTPS endpoint. Sandbox registration never sends network traffic.
`event_types` required	array

Response schema

Field	Type	Description
`id` required	string	Endpoint ID.
`url` required	string	HTTPS URL.
`event_types` required	array
`status` required	string	active
`created_at` required	string	ISO 8601 timestamp with timezone. Responses use UTC Z.
`signing_secret` required	string	Show once. Save in your secret manager.

HTTP responses and errors

201	Resource created in local sandbox. No live purchase.
400	Malformed JSON, cursor or idempotency header.
401	Missing, invalid, expired or revoked key.
403	Required scope not granted.
404	Resource unavailable in this account and environment, or label format unavailable.
405	Method not supported.
409	Idempotency conflict, request in progress, expired/mismatched quote or cancellation unavailable.
413	Body exceeds 256 KiB.
422	Schema or capability validation failure.
429	Enforced sandbox rate limit reached.
500	Unexpected PX failure.
502	Provider operation not confirmed. No blind booking retry.
503	Provider unavailable or live API not released.

Request example

curl --request POST \
  --url "$PX_BASE_URL/webhook-endpoints" \
  --header "Authorization: Bearer $PX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $PX_IDEMPOTENCY_KEY" \
  --data '{
  "url": "https://merchant.example.com/webhooks/px",
  "event_types": [
    "shipment.booked",
    "tracking.updated"
  ]
}'

Response example

{
  "id": "wh_test_1",
  "url": "https://merchant.example.com/webhooks/px",
  "event_types": [
    "shipment.booked"
  ],
  "status": "active",
  "created_at": "2026-10-04T10:25:00Z",
  "signing_secret": "whsec_TEST_PLACEHOLDER"
}

List webhook endpoints

GET/v1/webhook-endpoints

Lists this account/environment subscriptions without signing secrets. Revocation/deletion and live dispatcher are launch gaps. Production access remains disabled. Unreleased server adapters and database controls are under certification; hosted test credentials are unavailable.