Tracking Webhooks

Use webhooks to be notified about tracking statuses, deliveries, and other events

Introduction
Examples
FAQ

Webhook Events

Events are triggered by changes in objects you've created via the API. Every time an Event related to one of your objects is created, EasyPost will send a POST request to each of the webhook URLs set up for your account.

Webhooks Guide Event Object

Event objects are serialized into JSON and sent in the body of the request to your webhook URLs. The 'description' attribute is significant - it contains two values: a result object type, and an event name, separated by a period. For example, the description 'tracker.updated' indicates that the Event result attribute will contain a Tracker object that has just been updated.

Sample Webhook JSON

{
  "id": "evt_qatAiJDM",
  "object": "Event",
  "created_at": "2014-11-19T10:51:54Z",
  "updated_at": "2014-11-19T10:51:54Z",
  "description": "tracker.updated",
  "mode": "test",
  "previous_attributes": {
    "status": "unknown"
  },
  "pending_urls": [],
  "completed_urls": [],
  "result": {
    "id": "trk_Txyy1vaM",
    "object": "Tracker",
    "mode": "test",
    "tracking_code": "EZ4000000004",
    "status": "delivered",
    "created_at": "2014-11-18T10:51:54Z",
    "updated_at": "2014-11-18T10:51:54Z",
    "signed_by": "John Tester",
    "weight": 17.6,
    "est_delivery_date": "2014-08-27T00:00:00Z",
    "shipment_id": null,
    "carrier": "UPS",
    "public_url": "https://track.easypost.com/djE7...",
    "tracking_details": [
      {
        "object": "TrackingDetail",
        "message": "BILLING INFORMATION RECEIVED",
        "status": "pre_transit",
        "datetime": "2014-08-21T14:24:00Z",
        "tracking_location": {
          "object": "TrackingLocation",
          "city": null,
          "state": null,
          "country": null,
          "zip": null
        }
      },
      {
        "object": "TrackingDetail",
        "message": "ORIGIN SCAN",
        "status": "in_transit",
        "datetime": "2014-08-21T14:48:00Z",
        "tracking_location": {
          "object": "TrackingLocation",
          "city": "SOUTH SAN FRANCISCO",
          "state": "CA",
          "country": "US",
          "zip": null
        }
      },
      {
        "object": "TrackingDetail",
        "message": "DEPARTURE SCAN",
        "status": "in_transit",
        "datetime": "2014-08-22T08:51:00Z",
        "tracking_location": {
          "object": "TrackingLocation",
          "city": "SOUTH SAN FRANCISCO",
          "state": "CA",
          "country": "US",
          "zip": null
        }
      },
      {
        "object": "TrackingDetail",
        "message": "ARRIVAL SCAN",
        "status": "in_transit",
        "datetime": "2014-08-23T09:31:00Z",
        "tracking_location": {
          "object": "TrackingLocation",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "country": "US",
          "zip": null
        }
      },
      {
        "object": "TrackingDetail",
        "message": "OUT FOR DELIVERY",
        "status": "out_for_delivery",
        "datetime": "2014-08-24T08:10:00Z",
        "tracking_location": {
          "object": "TrackingLocation",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "country": "US",
          "zip": null
        }
      },
      {
        "object": "TrackingDetail",
        "message": "DELIVERED",
        "status": "delivered",
        "datetime": "2014-08-24T15:33:00Z",
        "tracking_location": {
          "object": "TrackingLocation",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "country": "US",
          "zip": null
        }
      }
    ]
  }
}

FAQ

How many webhook endpoints can I designate?: Currently there is not a limit.
How many times does EasyPost attempt to deliver the event to an endpoint?: After 6 failures, EasyPost will no longer attempt to send the webhook.
What HTTP status code do I need to return?: You would need to return a status code of 2XX, usually 200 works best.
How long do I have to respond?: You must respond with a successful response within 30 seconds. If there was not a response sent back, then the event will be sent again. It is best practices to receive the webhook, and then send the event to be processed by a background worker. That way you can immediately return a successful response and you will not receive the webhook again.
How can I test my webhook integration?: The best way to test webhooks for tracking is to create and purchase a shipment in Test mode. When you do this, you will get a test tracking event in one of the supported statuses (eg "in_transit", "delivered", etc.). If you are developing locally and need a public URL for your webhooks, you can set one up at beeceptor or a similar endpoint mocking service.
What are the possible tracker statuses?: The possible statuses are unknown, pre_transit, in_transit, out_for_delivery, available_for_pickup, return_to_sender, delivered, failure, and canceled.
How can I retry failed events?: Currently there is not a way to retry failed events.

Spend less on shipping today

EasyPost's multi-carrier Shipping API includes:

USPS Merchant Discount Pricing on ALL accounts
Instant access to USPS, UPS, FedEx, DHL, and 100+ carriers
Tracking, rating, address verification, and insurance features
FREE EasyPost testing with no upfront costs
Client libraries for .NET, Java, Ruby, Python, Node, PHP, and Go