01 / Quickstart
Receive ocean tracking updates
Create a destination for your HTTPS receiver, then subscribe a container, BOL, or booking to a schedule. Panvaya sends the normalized ocean tracking response to your receiver after a successful run.
- Use an active Panvaya API key with webhook access enabled for your organization.
- Register your receiver URL and choose how Panvaya authenticates to it.
- Create a subscription using the returned destination ID.
- Verify receiver authentication, deduplicate delivery IDs, and acknowledge with HTTP 2xx.
Your Panvaya API key authenticates setup requests. Receiver credentials authenticate deliveries to your server; use a separate secret for these.
02 / Schedule
Choose when to receive updates
Choose an interval from 5 minutes to 30 days, or daily times such as 09:00, 21:00 in an IANA timezone. Delivery times are approximate and can follow the scheduled time.
Optional startAt and endAt fields define the subscription window. For a future start, set runImmediately: false.
03 / Receiver
Register an HTTPS Destination
Before creating tracking subscriptions, register the public HTTPS URL where Panvaya should POST tracking updates. Keep receiver secrets separate from your Panvaya API key; credentials are never returned in API responses.
curl -X POST https://api.panvaya.com/api/v1/webhook-endpoints \
-H "X-API-Key: pv_live_your_key_here" \
-H "Idempotency-Key: 8c192cb3-04c6-481b-b315-422df39ddc92" \
-H "Content-Type: application/json" \
-d '{
"name": "Operations webhook receiver",
"environment": "live",
"url": "https://hooks.example.com/panvaya/ocean",
"authType": "API_KEY",
"authHeaderName": "X-Custom-Webhook-Secret",
"authSecret": "sec_prod_9f81a7b2..."
}'Supported Auth Modes- • NONE: Open endpoint with valid TLS certificate
- • API_KEY: Custom header name & secret key
- • STATIC_BEARER: Authorization: Bearer token
- • OAUTH2_CLIENT_CREDENTIALS: Token URL, Client ID & Secret
Receiver URL requirements- • Must be standard port 443 HTTPS
- • Must present a trusted, non-expired TLS certificate
- • Use a publicly reachable URL; private networks and localhost are unsupported
- • HTTP redirects (301/302) are rejected for security
04 / Subscriptions
Create Active Tracking Subscriptions
A subscription links a destination endpoint to a tracking target and a cadence. You can track by container, bol (Bill of Lading), or bk (Booking).
When authenticating with an API key, that key is automatically bound to the subscription for credit deduction.
curl -X POST https://api.panvaya.com/api/v1/webhook-subscriptions \
-H "X-API-Key: pv_live_your_key_here" \
-H "Idempotency-Key: 146ce001-01f1-43b9-af42-b068585f6358" \
-H "Content-Type: application/json" \
-d '{
"name": "High-priority container monitoring",
"endpointId": "0192a6b2-031f-7000-8000-000000000001",
"productCode": "WEBHOOK_SEA_TRACKING",
"requestConfig": {
"input": {
"container": "MSKU8094830",
"shipping_line_scac": "MSCU",
"include_route_data": true
}
},
"schedule": {
"type": "INTERVAL",
"intervalSeconds": 300,
"timezone": "UTC"
},
"externalReference": "order-po-98421",
"runImmediately": true
}'Idempotency: Always provide an Idempotency-Key header. Retrying with the same key returns the existing subscription without creating duplicates.
05 / Delivery Contract
Inbound Delivery Request Contract
When a scheduled tracking run completes, Panvaya issues an HTTPS POST request to your destination URL. The request includes delivery identification headers and a JSON normalized ocean response object with data and errors, including journey, locations, transports and containers.
POST /panvaya/ocean HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
X-Panvaya-Delivery-Id: 0192a71f-0a21-7000-8000-000000000042
X-Panvaya-Subscription-Id: 0192a6b2-031f-7000-8000-000000000001
X-Panvaya-Product: WEBHOOK_SEA_TRACKING
X-Panvaya-Environment: live
X-Panvaya-Sequence: 1
X-Panvaya-Timestamp: 1791633600
X-Panvaya-Schema-Version: v1
X-Panvaya-External-Reference: order-po-98421
X-Custom-Webhook-Secret: receiver_secret_here{
"data": {
"reference": {
"number": "MSKU8094830",
"type": "container"
},
"shipping_line": {
"scac": "MSCU",
"name": "Mediterranean Shipping Company"
},
"status": "IN_TRANSIT",
"journey": {
"origin": {
"location_id": 1,
"estimated_departure_at": null,
"actual_departure_at": null,
"estimated_arrival_at": null,
"actual_arrival_at": null
},
"port_of_lading": {
"location_id": 1,
"estimated_departure_at": null,
"actual_departure_at": "2026-10-04T08:15:00Z",
"estimated_arrival_at": null,
"actual_arrival_at": null
},
"port_of_discharge": {
"location_id": 2,
"estimated_departure_at": null,
"actual_departure_at": null,
"estimated_arrival_at": "2026-10-18T14:30:00Z",
"actual_arrival_at": null
},
"destination": {
"location_id": 2,
"estimated_departure_at": null,
"actual_departure_at": null,
"estimated_arrival_at": null,
"actual_arrival_at": null
}
},
"locations": [
{
"id": 1,
"name": "Shanghai",
"state": null,
"country": "China",
"country_code": "CN",
"locode": "CNSHA",
"latitude": 31.23,
"longitude": 121.47,
"timezone": "Asia/Shanghai"
},
{
"id": 2,
"name": "Los Angeles",
"state": "California",
"country": "United States",
"country_code": "US",
"locode": "USLAX",
"latitude": 33.74,
"longitude": -118.27,
"timezone": "America/Los_Angeles"
}
],
"transports": [
{
"id": 1,
"mode": "vessel",
"name": "MSC GULSUN",
"imo": 9839430,
"call_sign": null,
"mmsi": null,
"flag": null,
"vehicle_number": null,
"voyage_number": "639W"
}
],
"containers": [
{
"number": "MSKU8094830",
"equipment": null,
"status": "IN_TRANSIT",
"events": [
{
"id": 1,
"location_id": 1,
"event_code": "DEPA",
"event_name": "Departure from port",
"event_category": "transport",
"carrier_event_name": "Vessel departed",
"event_time": "2026-10-04T08:15:00Z",
"actual": true,
"transport_id": 1
},
{
"id": 2,
"location_id": 2,
"event_code": "ARRI",
"event_name": "Arrival at port",
"event_category": "transport",
"carrier_event_name": "Expected arrival",
"event_time": "2026-10-18T14:30:00Z",
"actual": false,
"transport_id": 1
}
]
}
],
"route_data": null
},
"errors": null
}X-Panvaya-Delivery-Id header as your idempotency key on receiver side. If a transient network glitch causes a retry, the delivery ID remains identical for that tracking update.06 / Operations
Manual Runs & Delivery Replay
You can trigger an on-demand tracking run immediately, or replay an existing delivery without touching the carrier or incurring credit charges:
1. On-Demand Immediate Run
Requests a new tracking update within the active start/end window. A successful run is billed. If pending deliveries prevent a new run, resolve them before retrying. Reuse the Idempotency-Key for the same request.
curl -X POST https://api.panvaya.com/api/v1/webhook-subscriptions/{subscriptionId}/run \
-H "X-API-Key: pv_live_your_key_here" \
-H "Idempotency-Key: a4c81f34-31e2-45a8-92cb-1f6b8648e3a2"2. Delivery Replay (Zero Credits)
Re-sends an earlier tracking update without another tracking charge. Live vessel metadata may change. Use the current lease_generation value from execution history in If-Match; refresh history if the API returns 412. Replay is available for 48 hours.
curl -X POST https://api.panvaya.com/api/v1/webhook-executions/{executionId}/replay \
-H "X-API-Key: pv_live_your_key_here" \
-H "If-Match: 1"07 / Reliability
Delivery Acknowledgement & Retries
Your receiver must respond within 10 seconds. Return the appropriate HTTP status code based on processing state:
HTTP 200 / 202 / 204
Acknowledges delivery success. Panvaya records the delivery as completed and will not re-attempt this run.
HTTP 408 / 429 / 5xx / Timeout
Treated as a transient failure. Panvaya retries automatically for up to 8 total attempts over 24 hours with exponential backoff.
Permanent Rejection: 4xx responses (except 408 and 429) such as 401 Unauthorized or 404 Not Found stop automatic retries. Correct your receiver or credentials, then replay the delivery within the replay window.
08 / Billing
Credits & Metering Model
Webhook Sea Tracking uses its own metered product code, WEBHOOK_SEA_TRACKING (default: 2 credits per successful tracking run).
- Successful tracking runs are billed once: This includes responses served from cache.
- Failed tracking runs are free: If tracking fails or returns a 404, zero credits are charged.
- Delivery retries are free: All delivery attempts and manual replays cost 0 credits.
Webhook access must be enabled for your organization. REST and webhook tracking share the distinct-shipment allowance. If credits or shipment allowance run out, the subscription is blocked with QUOTA_EXCEEDED (HTTP 402). After a top-up, activate it to resume. Pausing defers unsent deliveries; a tracking run already in progress may finish and be charged once.
09 / Verification
Receiver Launch Checklist
- Public HTTPS URL on standard port 443 with a valid TLS certificate.
- Receiver responds with HTTP 200 OK within 10 seconds of receiving POST.
- Deduplication implemented using the X-Panvaya-Delivery-Id header.
- Receiver-auth secret or OAuth credentials configured (or open endpoint with NONE).
- Billing API key has sufficient credit balance for scheduled runs.