Setting Up Webhooks

ShipStation API allows you to subscribe to webhooks to receive real-time updates for long-running asynchronous operations. This allows your application to move on to other work while the operation is running rather than being blocked until it completes.

It also allows ShipStation API to push updates to your application rather than having your application continually poll for updates. For example, you may subscribe to the track webhook event to automatically receive an update anytime a tracking event occurs. Rather than continually sending a request to the /v1/labels/:label_id/track endpoint to see if the tracking information has been updated since the last time you checked, you can subscribe to the track webhook event and ShipStation API will push the notification to your application via a webhook whenever the tracking details are updated.

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

Configuring Webhooks

Before you can begin receiving webhooks, you must configure your ShipStation API account with the HTTP endpoints you'd like for the webhooks to be sent to. You can do this through the ShipStation API Dashboard or through the API.

Requirements

You must be in the Production environment of the ShipStation API dashboard to set up webhooks.

Configure Using the Dashboard

Log in to your account Dashboard.
Go to Developer, then Webhooks.
Click the Add New Webhook button.
Select your Webhook Event and enter your Webhook URL. You can set up multiple URLs for the same Event.
Click the green checkmark icon to save your webhook.

Configure Using the API

To configure a webhook using the API, you'll need to provide a url and an event that will trigger the webhook. You'll send this data using the POST method to /v1/environments/webhooks. You may only configure one URL per event.

The payload for each type of webhook event will have a unique resource_type which indicates which type of event triggered the webhook.

You can use the following event names and corresponding resource types in your payload when you configure a webhook through the API:

Description	Event	Resource Type
Batch completed	`batch`	`API_BATCH`
Shipment rate updated	`rate`	`API_RATE`
Any tracking event	`track`	`API_TRACK`
Carrier connected	`carrier_connected`	`API_CARRIER_CONNECTED`
Sales Orders imported (Beta)	`sales_orders_imported`	`API_SALES_ORDERS_IMPORTED`
Order Source refresh complete (Beta)	`order_source_refresh_complete`	`API_ORDER_SOURCE_REFRESH_COMPLETE`
A requested report is ready	`report_complete`	`API_REPORT_COMPLETE`

Example Request

This example uses a batch event.

POST /v1/environment/webhooks

1
2
3
4
5
6
7
8
9
POST /v1/environment/webhooks HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
    "url": "https://example.com/batch",
    "event": "batch"
}

Testing Webhooks

You can use a service like requestbin.com to create temporary URLs to test webhooks. 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.

Webhook Payloads

We've included example payloads for the types of webhooks you can subscribe to below. You can expect to receive a message with the same structure as these examples whenever you subscribe to the corresponding event. You'll notice that each payload includes a resource_type and a resource_url. Some payloads will contain additional information as well.

When ShipStation API dispatches a webhook, we allow 10 seconds for you to acknowledge you have successfully received the payload (your listener should return a 2xx response to us). If we don't receive an acknowledgement within 10 seconds, the system will put the payload back into the queue and make a maximum of two additional attempts to dispatch the given payload. These attempts are typically separated by 30 minutes. However, this can swap to other timing intervals under certain conditions. If all three attempts receive no response, the event will be removed from the dispatch queue.

Example Batch Event Payload

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

Example Track Event Payload

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
{
  "resource_url": "https://api.shipengine.com/v1/tracking?carrier_code=usps&tracking_number=9400111298370264401222",
  "resource_type": "API_TRACK",
  "data": {
    "label_url": null,
    "tracking_number": "9400111298370264401222",
    "status_code": "IT",
    "carrier_detail_code": null,
    "status_description": "In Transit",
    "carrier_status_code": "NT",
    "carrier_status_description": "Your package is moving within the USPS network and is on track to be delivered the expected delivery date. It is currently in transit to the next facility.",
    "ship_date": "2020-06-30T16:09:00",
    "estimated_delivery_date": "2020-07-06T00:00:00",
    "actual_delivery_date": null,
    "exception_description": null,
    "events": [
      {
        "occurred_at": "2020-07-02T00:00:00Z",
        "carrier_occurred_at": "2020-07-02T00:00:00",
        "description": "In Transit, Arriving On Time",
        "city_locality": "",
        "state_province": "",
        "postal_code": "",
        "country_code": "",
        "company_name": "",
        "signer": "",
        "event_code": "NT",
        "event_description": "In Transit, Arriving on Time",
        "carrier_detail_code": null,
        "status_code": null,
        "latitude": null,
        "longitude": null
      },
      {
        "occurred_at": "2020-06-30T20:09:00Z",
        "carrier_occurred_at": "2020-06-30T16:09:00",
        "description": "Shipment Received, Package Acceptance Pending",
        "city_locality": "VERSAILLES",
        "state_province": "KY",
        "postal_code": "40383",
        "country_code": "",
        "company_name": "",
        "signer": "",
        "event_code": "TM",
        "event_description": "Shipment Received, Package Acceptance Pending",
        "carrier_detail_code": null,
        "status_code": null,
        "latitude": 37.8614,
        "longitude": -84.6646
      }
    ]
  }
}

Example Rate Event Payload

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

Example Carrier Connected Event Payload

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

Example Sales Order Imported Event Payload (Beta)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
{
  "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
      }]
  }]
}

Example Order Source Refresh Complete Event (Beta)

1
2
3
4
{
  "resource_url": "https://api.shipengine.com/v-beta/stores/se-0bdf1f26-5708-4e0b-a548-fd2a5720779f",
  "resource_type": "API_ORDER_SOURCE_REFRESH_COMPLETE"
}

Example Report Complete Event Payload

1
2
3
4
{
  "resource_url": "https://api.shipengine.com/adjustments/se-0bdf1f26-5708-4e0b-a548-fd2a5720779f",
  "resource_type": "API_REPORT_COMPLETE"
}