Skip to content

EasyPost Webhooks Documentation

Menu Location: Settings > System Integration > EasyPost Webhooks

Access Level: Administrator / Kiva Admin

Last Updated: 2026-03-01

Overview

The EasyPost Webhooks page manages automated notifications from EasyPost (your shipping label provider) about tracking events, delivery confirmations, and shipping exceptions, enabling real-time updates to customer orders and automated customer notifications.

Primary Functions:

  • Configure webhook endpoints for EasyPost events
  • Monitor incoming webhook notifications
  • View shipping event history and tracking updates
  • Troubleshoot delivery issues and exceptions
  • Automate customer notifications for shipping events
  • Track webhook delivery success and failures

Page Layout

Header Section

  • Page Title: "EasyPost Webhooks"
  • Webhook Status: Active/Inactive indicator
  • Configuration Button: Set up or update webhook URL
  • Test Webhook Button: Send test notification

Webhook Events Log

Table displaying recent webhook events:

  • Event Type (tracking update, delivery, exception, etc.)
  • Order Number
  • Tracking Number
  • Event Timestamp
  • Delivery Status
  • Customer Notified (Yes/No)
  • Event Details Link

Configuration Panel

  • Webhook URL (system-generated)
  • Enabled Events checkboxes
  • Notification Settings
  • Secret Key for validation

Statistics Dashboard

  • Total Webhooks Received (30 days)
  • Successful Processing Rate
  • Failed Webhooks
  • Most Common Event Types

Understanding EasyPost Webhooks

What are Webhooks?

Definition: Webhooks are automated messages sent from EasyPost to your KlCode system when shipping events occur, providing real-time updates without manually checking tracking information.

How They Work:

  1. Customer's package is scanned by carrier (USPS, FedEx, UPS)
  2. EasyPost receives tracking update from carrier
  3. EasyPost sends webhook notification to your system
  4. KlCode processes the event and updates order status
  5. Customer receives automated email/SMS notification (if enabled)
  6. Order page reflects current delivery status

Common Event Types:

  • Tracker Created: Tracking number generated
  • In Transit: Package picked up and moving
  • Out for Delivery: On delivery truck
  • Delivered: Successfully delivered
  • Failed Delivery Attempt: Delivery attempted but failed
  • Exception: Problem occurred (damaged, lost, delayed)
  • Available for Pickup: Package at facility for customer pickup
  • Return to Sender: Package being returned

Webhook Configuration

Enabling Webhooks

Purpose: Activate webhook notifications from EasyPost

Steps:

  1. Click "Configure Webhooks" button
  2. System displays your unique webhook URL
  3. Copy webhook URL to clipboard
  4. Log into your EasyPost dashboard
  5. Navigate to "Webhooks" section
  6. Click "Add Webhook"
  7. Paste your KlCode webhook URL
  8. Select events to send (select all recommended)
  9. Save webhook in EasyPost
  10. Return to KlCode and click "Test Connection"
  11. Verify test webhook received successfully

Requirements:

  • Active EasyPost account
  • Administrator access in both systems
  • SSL certificate enabled (https required)

Selecting Events to Track

Recommended Events:

  • ✅ tracker.created - Tracking number assigned
  • ✅ tracker.updated - Any tracking status change
  • ✅ tracker.delivered - Package delivered
  • ✅ tracker.in_transit - Package in transit
  • ✅ tracker.out_for_delivery - Out for delivery
  • ✅ tracker.available_for_pickup - Ready for pickup
  • ✅ tracker.return_to_sender - Being returned
  • ✅ tracker.failure - Delivery failed
  • ✅ tracker.exception - Exception occurred

Optional Events:

  • batch.created - Label batch created
  • batch.updated - Batch status changed
  • refund.successful - Refund processed

Configuration:

  1. In KlCode Webhook Settings, check desired events
  2. Save configuration
  3. Events are filtered on receipt
  4. Unchecked events ignored if received

Webhook Security

Secret Key Validation:

  • System generates unique secret key
  • EasyPost signs each webhook with this key
  • KlCode validates signature on receipt
  • Invalid signatures rejected (prevents fake webhooks)

Security Best Practices:

  1. Never share your webhook URL publicly
  2. Rotate secret key if compromised
  3. Monitor for unusual webhook activity
  4. Review failed validation attempts
  5. Use HTTPS only (never HTTP)

Monitoring Webhook Events

Viewing Webhook Log

Purpose: Review all incoming shipping events

Steps:

  1. Navigate to EasyPost Webhooks page
  2. View list of recent webhook events
  3. Use filters to narrow results:
    • Date range
    • Event type
    • Order number
    • Delivery status
    • Success/failure
  4. Click any event to view full details

Event Details Include:

  • Full tracking event data
  • Customer information
  • Order details
  • Notification sent status
  • Processing timestamp
  • Any errors encountered

Understanding Event Details

Tracking Update Example: 

Event Type: tracker.updated
Status: in_transit
Status Detail: Arrived at USPS facility
Location: Portland, OR 97201
Timestamp: 2026-03-01 10:32:15
Carrier: USPS
Tracking Code: 9400111899562891234567
Order: #12345
Customer Notified: Yes (email sent)

Key Information:

  • Status: Current delivery status
  • Status Detail: Specific carrier message
  • Location: Where package currently is
  • Timestamp: When event occurred
  • Carrier: Shipping carrier (USPS, FedEx, UPS)
  • Customer Notified: If automatic notification sent

Filtering and Searching

Search Options:

  • Order Number: Find webhooks for specific order
  • Tracking Number: Look up specific package
  • Customer Name/Email: See all events for customer
  • Date Range: View events within timeframe
  • Event Type: Filter by specific event (delivered, exception, etc.)
  • Status: Show only failed or successful processing

Common Searches:

  1. "Show all delivered today" - Delivered events, today's date
  2. "Find exceptions this week" - Exception events, last 7 days
  3. "Failed webhooks" - Processing failed filter
  4. "Order #12345 history" - Search by order number

Customer Notifications

Automated Notification Settings

Configure Automatic Emails/SMS:

  1. Go to Webhook Settings
  2. Enable "Customer Notifications"
  3. Select which events trigger notifications:
    • ✅ Out for Delivery (high value - day-of notice)
    • ✅ Delivered (confirmation)
    • ✅ Exception (problem alert)
    • ⬜ In Transit (optional - can be noisy)
    • ⬜ Available for Pickup (if applicable)
  4. Choose notification method:
    • Email only
    • SMS only
    • Both email and SMS
  5. Customize notification templates
  6. Save settings

Best Practices:

  • Always notify for: Delivered, Exception
  • Consider notifying for: Out for Delivery
  • Skip unless needed: In Transit updates (too frequent)
  • Test notifications before enabling globally

Notification Templates

Customize Message Content:

  1. Click "Edit Templates" in notification settings
  2. Select event type (Delivered, Out for Delivery, etc.)
  3. Edit email template:
    • Subject line
    • Body text
    • Personalization tags available
  4. Edit SMS template (if enabled):
    • Message text (160 char limit)
    • Include tracking link
  5. Preview templates
  6. Save changes

Personalization Tags:

  • {{customer_name}} - Customer first name
  • {{order_number}} - Order number
  • {{tracking_number}} - Tracking code
  • {{carrier}} - Shipping carrier
  • {{tracking_url}} - Link to track package
  • {{delivery_date}} - Expected/actual delivery date
  • {{status_detail}} - Carrier status message

Example Templates:

Out for Delivery: 

Subject: Your order #{{order_number}} is out for delivery today!

Hi {{customer_name}},

Great news! Your order is on the delivery truck and should arrive today.

Track your package: {{tracking_url}}

Thanks for your business!

Delivered: 

Subject: Your order #{{order_number}} has been delivered

Hi {{customer_name}},

Your order has been delivered! 

Delivered: {{delivery_date}}
Tracking: {{tracking_number}}

We hope you enjoy your delivery. Questions? Just reply to this email.

Common Use Cases

Use Case 1: Monitoring Daily Deliveries

Goal: Track which orders were delivered today

Steps:

  1. Navigate to EasyPost Webhooks page
  2. Set filter: Event Type = "Delivered"
  3. Set filter: Date = "Today"
  4. Review list of delivered orders
  5. Cross-reference with expected deliveries
  6. Investigate any missing deliveries
  7. Export list for records

Tips:

  • Check daily in afternoon (most deliveries by then)
  • Compare count to expected delivery count
  • Look for patterns in delivery times
  • Note any recurring delivery issues by location

Use Case 2: Handling Delivery Exceptions

Goal: Quickly identify and resolve shipping problems

Steps:

  1. Filter webhook log by Event Type = "Exception"
  2. Review each exception:
    • Weather delay: Monitor, no action needed
    • Damaged package: Contact customer, offer replacement
    • Incorrect address: Contact customer, verify address
    • Refused delivery: Reach out to understand why
    • Lost package: File claim with carrier
  3. Document resolution steps
  4. Update customer via phone or email
  5. Process refund/replacement as needed
  6. Update customer address if needed

Example Exceptions:

  • "Addressee not available" - Customer not home
  • "Damaged during transit" - File claim
  • "Incorrect address" - Update and reship
  • "Weather delay" - Normal, communicate to customer
  • "Held at post office" - Notify customer to pick up

Use Case 3: Proactive Customer Communication

Goal: Keep customers informed before they ask

Steps:

  1. Set up automated notifications for:
    • Out for Delivery (morning alert)
    • Delivered (confirmation)
    • Exception (problem alert)
  2. Review webhook log daily for unusual events
  3. For exceptions, proactively email customer:
    • Explain situation
    • Provide expected resolution
    • Offer assistance
  4. Monitor customer responses
  5. Track reduction in "where is my order?" inquiries

Benefits:

  • Reduces support inquiries by 30-50%
  • Improves customer satisfaction
  • Builds trust through transparency
  • Catches issues before customer notices

Use Case 4: Investigating Missing Package

Goal: Determine what happened to package customer says wasn't delivered

Steps:

  1. Search webhooks by order number or tracking number
  2. Review complete event history chronologically
  3. Check final status:
    • Delivered: Carrier says delivered
    • Check delivery location detail
    • Ask customer to check mailbox, porch, neighbors
    • Request photo proof from carrier
    • Failed Delivery: Customer wasn't available
    • Notify customer to arrange redelivery
    • Exception: Problem occurred
    • Review exception details
    • Take appropriate action
    • No Recent Updates: Lost in transit
    • File lost package claim
    • Send replacement to customer
  4. Document findings
  5. Communicate resolution to customer
  6. Process refund/replacement if necessary

Use Case 5: Analyzing Delivery Performance

Goal: Review carrier performance and identify improvement opportunities

Steps:

  1. Export webhook data for past 30-90 days
  2. Analyze in spreadsheet:
    • Calculate on-time delivery rate by carrier
    • Count exceptions by type
    • Identify problematic delivery zones (frequent issues)
    • Calculate average delivery time
    • Review customer notification engagement
  3. Identify patterns:
    • Specific carrier underperforming
    • Certain zip codes with issues
    • Days of week with more exceptions
  4. Take action:
    • Consider switching carriers for problem zones
    • Update delivery day messaging
    • Adjust packing for damage-prone routes
    • Communicate known delays to customers proactively
  5. Track improvements monthly

Key Metrics:

  • On-time delivery rate (target: 95%+)
  • Exception rate (target: <5%)
  • Average delivery time (compare to carrier promises)
  • Customer notification open rate

Troubleshooting

Issue 1: Webhooks Not Being Received

Symptoms: No new webhook events in log, but shipments are going out

Check:

  1. Verify webhook is enabled in EasyPost dashboard
  2. Confirm webhook URL is correct in EasyPost
  3. Test webhook connection from this page
  4. Check if SSL certificate is valid (https required)
  5. Review EasyPost webhook delivery log for errors
  6. Verify no firewall blocking webhooks

Solutions:

  1. Re-enter webhook URL in EasyPost dashboard
  2. Click "Test Webhook" to verify connectivity
  3. Check server logs for rejected requests
  4. Ensure webhook URL uses https:// not http://
  5. Verify EasyPost account active and paid
  6. Contact Kiva Logic if persistent

If Problem Persists: Export EasyPost webhook delivery log showing failures, contact Kiva Logic support.

Issue 2: Duplicate Webhook Events

Symptoms: Same tracking event appearing multiple times, customers receiving duplicate notifications

Causes:

  • EasyPost retrying failed webhooks
  • Webhook misconfigured (multiple URLs)
  • Event triggered multiple times by carrier

Solutions:

  1. Check EasyPost dashboard for multiple webhook URLs
  2. Remove duplicate webhook configurations
  3. System automatically deduplicates, verify it's enabled
  4. Review webhook processing logs for errors causing retries
  5. If customer complained, apologize and explain

Prevention:

  • Only configure one webhook URL in EasyPost
  • Enable deduplication in webhook settings
  • Monitor for processing errors

Issue 3: Customer Not Receiving Notifications

Symptoms: Webhook received successfully but customer didn't get email/SMS

Check:

  1. Verify customer notifications enabled in settings
  2. Check which events trigger notifications
  3. Verify customer email address is valid
  4. Check customer's email subscription status (not unsubscribed)
  5. Review Email Pending queue for stuck messages
  6. Check SMS queue if using text notifications
  7. Review customer's notification preferences

Solutions:

  1. Enable notifications for the specific event type
  2. Verify customer contact information is current
  3. Check spam folder (ask customer)
  4. Review email template isn't broken
  5. Resend notification manually if needed
  6. Update customer email if bouncing

Issue 4: Webhook Processing Failures

Symptoms: "Failed" status on webhook events in log

Common Errors:

  • Order not found (order was deleted or archived)
  • Invalid tracking number format
  • Customer record missing
  • Email sending failed
  • Database connection issue

Solutions:

  1. Review error message for specific issue
  2. Verify order still exists in system
  3. Check tracking number format is valid
  4. Ensure customer record intact
  5. Retry failed webhooks manually
  6. Fix underlying issue before retrying

Retry Process:

  1. Locate failed webhook in log
  2. Click "Retry" button
  3. System re-processes the event
  4. Verify successful processing
  5. Check customer received notification if applicable
  • EasyPost Settings - Configure EasyPost API integration
  • EasyPost Validations - Address validation logs
  • Print Labels - Create shipping labels
  • Orders - View order shipping status
  • Email Pending - Monitor outgoing notifications

Typical Workflow:

  1. Orders → Print Labels → EasyPost Creates Tracking
  2. EasyPost Webhooks → Receive Tracking Updates → Update Order Status
  3. EasyPost Webhooks → Trigger Notification → Customer Notified

Permissions & Access

Required Access Level: Administrator

Access Level Capabilities:

  • Manager: View webhook log only
  • Administrator: View, configure, test, retry failed webhooks
  • Kiva Admin: All features + webhook URL regeneration + advanced settings

Restricted Features:

  • Webhook Configuration: Requires Administrator
  • Edit Notification Templates: Requires Administrator
  • Regenerate Webhook URL: Requires Kiva Admin only

Best Practices

Configuration

  1. Enable all tracking event types (comprehensive data)
  2. Test webhooks thoroughly before relying on them
  3. Monitor webhook health weekly
  4. Document any custom configurations
  5. Keep secret key secure

Customer Notifications

  1. Notify for: Out for Delivery, Delivered, Exceptions
  2. Skip "in transit" updates (too frequent, low value)
  3. Personalize notification templates
  4. Test notifications before enabling globally
  5. Monitor notification open rates
  6. Include tracking link in all notifications

Monitoring

  1. Review webhook log daily for exceptions
  2. Export weekly reports for analysis
  3. Track on-time delivery rate
  4. Investigate failed webhooks promptly
  5. Monitor customer notification delivery rate

Issue Resolution

  1. Respond to exceptions within 24 hours
  2. Proactively contact customers about problems
  3. Document resolutions in order notes
  4. Track recurring issues and address root cause
  5. Communicate with carriers about persistent problems

Things to Avoid

  • ❌ Don't ignore exception webhooks
  • ❌ Don't disable webhooks without alternative tracking
  • ❌ Don't over-notify customers (causes fatigue)
  • ❌ Don't share webhook URL publicly
  • ❌ Don't delete webhook logs (needed for investigations)
  • ❌ Don't assume "delivered" means customer received (check details)

Quick Reference Card

Task Action/Location
View today's deliveries Filter: Event=Delivered, Date=Today
Find delivery exceptions Filter: Event=Exception
Search order tracking Search by order number
Test webhook connection Click "Test Webhook" button
Enable customer notifications Webhook Settings > Customer Notifications
Retry failed webhook Failed event > "Retry" button
View delivery details Click webhook event row
Export webhook data Filter desired events > "Export" button
Edit notification templates Settings > "Edit Templates"
Check webhook status Header shows Active/Inactive

FAQs

How quickly do webhooks arrive after carrier scans package?

Typically within 1-5 minutes. EasyPost receives carrier updates in near real-time and forwards via webhook immediately. Delays usually indicate carrier system issues, not webhook issues.

What if carrier shows delivered but customer says they didn't receive it?

Check webhook details for delivery location. Carrier often notes "front porch" or "mailbox". Ask customer to check those locations and neighbors. Request proof of delivery from carrier if needed. Wait 24 hours before filing claim (often found).

Can I resend a notification to a customer?

Yes, locate the webhook event, click "View Details", then click "Resend Notification". Customer receives the notification email/SMS again.

Why do some tracking events not trigger webhooks?

Either: (1) Event type not enabled in EasyPost webhook settings, (2) Event not supported by carrier, or (3) Carrier didn't provide that level of detail. Most common events (delivered, in transit, exception) always fire.

What's the difference between "in transit" and "out for delivery"?

"In transit" means package is moving through carrier's network. "Out for delivery" means package is on the delivery truck for final delivery that day. "Out for delivery" is much more valuable to notify customers about.

How long are webhook events stored?

12 months in active system. Older events archived but retrievable by Kiva Admin if needed for investigations.

Can I manually add a tracking event?

No, webhooks come from EasyPost only. You can manually update order status, but this doesn't create a webhook event. Webhooks reflect actual carrier tracking data.

What should I do if webhook URL is compromised?

Contact Kiva Logic immediately to regenerate webhook URL. Update new URL in EasyPost dashboard. Monitor for suspicious webhook activity. Review security practices.

End of Documentation

For additional help, contact your system administrator or Kiva Logic support.