Register a webhook subscription via POST /api/v4/webhooks with event types including SHIPMENT_STATUS_UPDATE and ESTIMATED_DELIVERY_UPDATE; provide a publicly reachable HTTPS endpoint URL and store the returned webhookId
Validate inbound webhook requests by reading the p44-signature header and comparing an HMAC-SHA256 digest of the raw request body against the shared secret stored at subscription time
Parse the payload's shipmentStatusEvents array; each event contains a statusCode (p44 milestone code such as InTransit, OutForDelivery, DeliveryAttempted), an eventDateTime in ISO 8601 UTC, and a statusReason object
Map p44 statusCodes to your internal canonical states using a lookup table; treat any unmapped code as UNKNOWN rather than discarding, and emit an alert for manual review
Persist each milestone with the shipmentId, carrier SCAC, event timestamp, and ingestion timestamp; use the eventId field for idempotency to prevent duplicate inserts on webhook retries
Acknowledge the webhook by returning HTTP 200 within 5 seconds; if processing is slow, enqueue the payload to a message queue and process asynchronously before the p44 retry window expires
Known gotchas
project44 retries unacknowledged webhooks with exponential backoff up to 24 hours; if your endpoint returns a 5xx, expect duplicate delivery; idempotency on eventId is mandatory
The estimatedDeliveryWindow in predictive ETA events contains both an earliest and latest ISO 8601 timestamp; consuming only the latest field and treating it as a single ETA causes display errors when the window spans midnight
p44 statusCodes are versioned; the same physical event (e.g. arrived at terminal) may be reported under different codes depending on carrier EDI capability; always include the rawCarrierStatus passthrough field in your storage schema
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp