Create a webhook endpoint in your application to receive POST requests from EasyPost; the endpoint must respond with HTTP 2xx within a few seconds.
Register the endpoint with EasyPost via POST /v2/webhooks with body: {url: 'https://your-domain.com/easypost-webhook'} — optionally include webhook_secret for HMAC signing.
When a webhook is received, extract the X-Hmac-Signature header value and compute your own HMAC-SHA256 of the raw request body using your webhook secret; compare the values using a constant-time comparison to validate authenticity.
Parse the event object from the JSON body; the result.object field identifies the event type (e.g., Tracker, Shipment, Insurance) and result.status or result.description describes what changed.
Acknowledge receipt immediately with HTTP 200 before performing any slow processing; use a queue to handle the event asynchronously to avoid timeout retries from EasyPost.
Known gotchas
EasyPost will retry webhook deliveries on non-2xx responses up to a certain number of times with backoff; idempotent processing is essential because you may receive the same event more than once.
The HMAC signature must be computed over the raw request body bytes before any JSON parsing; parsing first and re-serializing to compare will fail if key order changes.
Webhook secrets are optional in EasyPost but strongly recommended in production; without signature validation, any party who knows your webhook URL can POST fake events.
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