Setting Up Webhooks

ShipEngine exposes asynchronous operations for long running operations such as batch labels and rates. Webhooks allow the ShipEngine servers to contact your servers when an operation changes state, such as a batch label creation completion.

Additionally, webhooks are invoked when a shipment is tracked via the tracking endpoint when there are updates to the tracked shipment.

If you're new to webhooks, you can read this guide for more information.

Retry & Backoff

Webhook delivery will be attempted 3 times with a 2 hour delay between each attempt after which it will be discarded.

Configure Webhooks using the Dashboard

  1. Log into the ShipEngine Portal.
  2. Select API Management.
  3. Select the Webhooks tab.
  4. Follow the options on the screen to configure your account.

API Dashboard

Configure Webhooks using the API

To create a webhook using the API, you'll need to provide a URL and an event that will trigger the webhook. Please note that only one webhook can exist for each event. Multiple Webhooks for the same event are not supported. See the following table for a list of available events.

Event Event Value
Batch Completed batch
Shipment rate updated rate
Any tracking event track
Carrier Connected carrier_connected
Sales Orders Imported (Beta) sales_orders_imported
Order Source Refresh Complete (Beta) order_source_refresh_complete

The requestbin.com URLs below can be generated from RequestBin.com. You can use the service to create a free HTTPS endpoint. Any HTTP requests sent to that endpoint will be recorded with the associated payload and headers so you can observe the data sent from our webhooks before configuring your application to accept it.

Warning

HTTP 409 Conflict

If you create a webhook for an event that already exists, you'll receive an HTTP 409 Conflict error when your request is sent. If this occurs, be sure to review the list of webhooks, and delete the existing webhook for the event before resubmitting your request.

Example Request

curl -iX POST https://api.shipengine.com/v1/environment/webhooks \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '{
  "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
  "event": "batch"
}'
  • curl

Example Response

{
  "webhook_id": "5519",
  "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
  "event": "batch"
}

Tracking Payload

Info

Event Timestamps

carrier_occurred_at is the timestamp of the event received from the carrier, it is assumed to be the local time of where the event occurred.

occurred_at is the UTC based time of the event's occurrence.

Warning The carried_occurred_at event property is not yet fully supported across all carriers.

{
  "resource_url": "https://api.shipengine.com/v1/tracking/usps/9361269903502070406152",
  "resource_type": "API_TRACK",
  "data": {
    "links": {
      "self": {
        "href": "https://api.shipengine.com/v1/tracking/usps/9361269903502070406152"
      },
      "label": null
    },
    "tracking_number": "9361269903502070406152",
    "status_code": "DE",
    "status_description": "Delivered",
    "carrier_status_code": "01",
    "carrier_status_description": "Your item was picked up at the post office...",
    "shipped_date": "2019-07-25T05:00:00.000Z",
    "estimated_delivery_date": null,
    "actual_delivery_date": "2019-07-25T15:24:46.657Z",
    "exception_description": null,
    "events": [
      {
        "occurred_at": "2019-09-13T12:32:00Z",
        "carrier_occurred_at": "2019-09-13T05:32:00",
        "description": "Arrived at USPS Facility",
        "city_locality": "OCEANSIDE",
        "state_province": "CA",
        "postal_code": "92056",
        "country_code": "",
        "company_name": "",
        "signer": "",
        "event_code": "U1"
      }
    ]
  }
}

Tracking Status Codes

status_code explanation
AC Accepted
IT In Transit
DE Delivered
EX Exception
UN Unknown
AT Delivery Attempt

Rates Payload

{
  "resource_url": "https://api.shipengine.com/v1/shipments/se-2120221/rates",
  "resource_type": "API_RATE"
}

Batches Payload

{
  "resource_url": "https://api.shipengine.com/v1/batches/se-1013119",
  "resource_type": "API_BATCH"
}

Carrier Connected Payload

{
  "resource_url": "https://api.shipengine.com/v1/carriers/se-1234",
  "resource_type": "API_CARRIER_CONNECTED"
}

Sales Order Imported Payload (beta)

{
  "resource_url": "https://api.shipengine.com/v-beta/sales_orders",
  "resource_type": "API_SALES_ORDERS_IMPORTED",
  "data": [
  {
    "sales_order_id": "2078df4d-49c1-53da-837a-ad2781b782e0",
    "external_order_id": "611699195963",
    "external_order_number": "SH21622",
    "order_source":
      {
        "order_source_id": "4e4af80f-6974-48b6-b88f-e46f1c2a0b28",
        "order_source_nickname": "Shippity Shop Shopify",
        "order_source_code": "shopify",
        "order_source_friendly_name": "Shopify",
        "refresh_info":
        {
          "status": "idle",
          "last_refresh_attempt": "2018-09-12T19:29:21.657Z",
          "refresh_date": "2018-09-12T19:29:16.837Z"
        },
        "active": true
      },
      "sales_order_status":
      {
        "payment_status": "paid",
        "fulfillment_status": "unfulfilled",
        "is_cancelled": false
      },
      "order_date": "2018-09-12T19:18:12Z",
      "created_at": "2018-09-12T19:29:18.69Z",
      "modified_at": "2018-09-12T19:29:18.69Z",
      "payment_details":
      {
        "subtotal":
        {
          "currency": "usd",
          "amount": 40.0
        },
        "estimated_shipping":
        {
          "currency": "usd",
          "amount": 0.0
        },
        "estimated_tax":
        {
          "currency": "usd",
          "amount": 0.0
        },
        "grand_total":
        {
          "currency": "usd",
          "amount": 40.0
        }
      },
      "customer":
      {
        "name": "Amanda Miller",
        "phone": "555-555-5555",
        "email": "[email protected]"
      },
      "bill_to":
      {
        "email": "[email protected]",
        "address":
        {
          "name": null,
          "phone": null,
          "company_name": null,
          "address_line1": "",
          "address_line2": null,
          "address_line3": null,
          "city_locality": null,
          "state_province": null,
          "postal_code": null,
          "country_code": null,
          "address_residential_indicator": "no"
        }
      },
      "ship_to":
      {
        "name": "Amanda Miller",
        "phone": "555-555-5555",
        "address_line1": "525 S Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "country_code": "US",
        "address_residential_indicator": "yes"
      },
      "sales_order_items": [
      {
        "sales_order_item_id": "6f8f3f51-7a5a-50b2-a842-d6e89a5b5b26",
        "line_item_details":
        {
          "name": "Bubble Popper 4XL",
          "sku": "BUB-1-T",
          "weight":
          {
            "value": 2.8,
            "unit": "ounce"
          }
        },
        "ship_to":
        {
          "name": "Amanda Miller",
          "phone": "555-555-5555",
          "address_line1": "525 S Winchester Blvd",
          "city_locality": "San Jose",
          "state_province": "CA",
          "postal_code": "95128",
          "country_code": "US",
          "address_residential_indicator": "yes"
        },
        "requested_shipping_options":
        {
          "shipping_service": null,
          "ship_date": null
        },
        "price_summary":
        {
          "unit_price":
          {
            "currency": "usd",
            "amount": 40.0
          },
          "estimated_tax":
          {
            "currency": "usd",
            "amount": 0.0
          },
          "estimated_shipping": null,
          "total":
          {
            "currency": "usd",
            "amount": 40.0
          }
        },
        "quantity": 1,
        "is_gift": false
      }]
  }]
}