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"
}'

Example Response

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

Tracking Payload

{
  "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": [
      {
        "event_date": "2019-07-25T15:24:46.657Z",
        "description": "Delivered, Individual Picked Up at Post Office",
        "city_locality": "AUSTIN",
        "state_province": "TX",
        "postal_code": "78721",
        "country_code": "",
        "company_name": "",
        "signer": ""
      }
    ]
  }
}

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": "Greg Smith",
        "phone": null,
        "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": "Greg Smith",
        "phone": "",
        "company_name": null,
        "address_line1": "3800 N LAMAR BLVD STE 220",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "Austin",
        "state_province": "",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "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": "Greg Smith",
          "phone": "",
          "company_name": null,
          "address_line1": "3800 N LAMAR BLVD STE 220",
          "address_line2": null,
          "address_line3": null,
          "city_locality": "Austin",
          "state_province": "",
          "postal_code": "78756",
          "country_code": "US",
          "address_residential_indicator": "no"
        },
        "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
      }]
  }]
}