Ingest a project44 push webhook for shipment milestone events and reconcile milestone codes into a canonical tracking status

Steps

1. 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
2. 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
3. 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
4. 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
5. 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
6. 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