usps-webhooks

USPS Webhooks

USPS delivers webhooks through the Subscriptions - Tracking API (v3.2). You create a subscription (POST /subscriptions) with a listenerURL, filterProperties (by Mailer ID or tracking number), and an optional 32-char secret. USPS then POSTs a notification to your listener URL every time a tracked package updates.

When to Use This Skill

• How do I receive USPS tracking webhooks?
• How do I verify the USPS X-HMAC webhook signature?
• How do I create a USPS tracking subscription?
• How do I handle Delivered or Out for Delivery tracking events?
• Why is my USPS webhook signature verification failing?

Verification (core)

USPS signs timestamp + payload — the notification envelope's timestamp field concatenated with the raw, stringified payload field — with HMAC-SHA256 keyed on your subscription secret, and sends the Base64 digest in the X-HMAC header (deprecated alias: hmac-header).

You must parse the envelope to read timestamp and payload, then compute the HMAC over their concatenation. Do not re-serialize the inner payload — sign the raw string exactly as received. Compare timing-safe.

The OAuth2 token (used to create subscriptions) is not sent on delivery. Per-message authenticity comes from the X-HMAC signature and/or IP allowlisting. If you set no secret and no IP allowlist, there is no per-message verification.

When USPS_WEBHOOK_SECRET is unset, a subscription created without a secret sends no X-HMAC header at all — there is nothing to verify. Do not pass the missing secret into createHmac / hmac.new; that throws and turns a configuration problem into an opaque 500. The examples here branch explicitly: they log a one-time warning that notifications are being processed with no per-message verification (and that IP allowlisting should be used instead), then process the delivery. Swap that branch for a rejection if your deployment cannot rely on an allowlist — see references/verification.md.