How to create, manage, and use webhooks that will post to an endpoint when certain events occur in ShipStation.
If you're using ShipStation's REST API to communicate order information, or if you're using a third-party system that wants to pull data from ShipStation, it may be beneficial for you to set up webhooks. After you set up webhooks, ShipStation can push alerts when certain events occur in your account. These alerts will help guide the system to an endpoint that can be used to gather data from the ShipStation account.
Webhooks are an API process that allows ShipStation to push live updates to a target URL endpoint when certain actions occur within your ShipStation account. When triggered, ShipStation will make an API POST call to deliver a payload of data to the target URL that will include a follow-up resource_url that can be used to gather specific information related to the orders or shipments. A webhook will post the payload to the target URL within a few minutes of the action that triggered it.
You can create the following webhooks in ShipStation:
-
On New Orders (ORDER_NOTIFY)
-
On New Items (ITEM_ORDER_NOTIFY)
-
On Orders Shipped (SHIP_NOTIFY)
-
On Items Shipped (ITEM_SHIP_NOTIFY)
-
On Items Shipped by Fulfilment Provider (FULFILLMENT_SHIPPED)
-
On Items Rejected by Fulfilment Provider (FULFILLMENT_REJECTED)
The On New Orders and On New Items webhook types relate to order data. These webhooks trigger whenever a new order is created in ShipStation in any status other than Awaiting Payment, or when an order in Awaiting Payment is updated to any status other than Cancelled.
-
A webhook payload will be created for each import action that creates at least one new paid order.
-
All orders created at the same time will be included in a single webhook payload.
The On Orders Shipped and On Item Shipped webhook types relate to shipment data. These webhooks trigger when a new outbound shipping label is generated for an order. The webhooks will not be triggered for return shipments or for fulfilments created either through a fulfilment partner like FBA or by using the Mark as Shipped action.
-
If creating shipments individually, each shipment will trigger its own webhook.
-
If you create shipments in a batch, each batch will trigger a single webhook.
The On Items Shipped By Fulfilment Provider and On Items Rejected By Fulfilment Provider webhook types relate to fulfillment data. These webhooks trigger when a delegated order is moved from Pending Fulfillment to Shipped status and when a fulfilment provider rejects an order delegated to them by a vendor, respectively.
Additionally, On Items Shipped By Fulfilment Provider will trigger when using the Mark as Shipped action.
You can create new webhooks in your ShipStation account in two different ways:
-
API Calls
-
ShipStation Account Settings
This section explains how to create webhooks through the ShipStation Settings page. For information on using API calls, see our in-depth API documentation for more details on how to list webhooks, subscribe to a webhook, and unsubscribe from webhooks.
To create a webhook within ShipStation:
-
Select webhooks from the set of options.
Webhook Option Greyed Out
If you do not already have any webhooks created, the option will be grey.
-
Click Add a Webhook.
-
Set the Name (100-character maximum), Type, whether the webhook applies to all stores or a specific store, and the target URL (200-character maximum).
-
Click Save to create the webhook after you have entered the details.
You can remove existing webhooks in your ShipStation account in two ways:
-
API Calls
-
ShipStation Account Settings
This section explains how to remove webhooks through the ShipStation Settings page. For information on using API calls, see our in-depth API documentation for more details on removing webhooks.
To remove a webhook within ShipStation:
Regardless of how the webhook was created, you can only modify an existing webhook through your ShipStation Account Settings.
To modify an existing webhook:
When a webhook is triggered, ShipStation makes an API POST call to the target URL.
This call includes a payload related to the action and newly created data:
-
resource_url: The endpoint that will need to be contacted to gather data related to the action that triggered the webhook. The resource_url contains several URL parameters:
-
storeId: ShipStation's internal identifier for the store.
storeIdwill not be included if the webhook affects all stores. -
importBatch or batchId: ShipStation's internal identifiers for the Import action (for
ORDERwebhooks) or Label Creation action (forSHIPwebhooks). -
includeOrderItems or includeShipmentItems: Controls whether items are included in the response when contacting the resource_url. If using an
ITEMwebhook, this will be set to True.
-
-
resource_type: The type of webhook that triggered the payload.
To use the webhook payload, you must make an API GET call to the ShipStation REST API that uses the resource_url as the endpoint. When performing this API call, you must include an authentication header, just like other API calls made to ShipStation. See our in-depth API documentation for more details on API authentication.
When contacting the resource_url, the response will follow the same structure as the List Orders call (for ORDER webhooks) or List Shipments call (for SHIP webhooks.)
Here are some examples of webhook payloads:
|
On New Orders (ORDER_NOTIFY) {"resource_url":"https://ssapiX.shipstation.com/orders?storeID=123456&importBatch=1ab23c4d-12ab-1abc-a1bc-a12b12cdabcd","resource_type":"ORDER_NOTIFY"}
|
|
On New Items (ITEM_ORDER_NOTIFY) {"resource_url":"https://ssapiX.shipstation.com/orders?storeID=123456&importBatch=1ab23c4d-12ab-1abc-a1bc-a12b12cdabcd&includeOrderItems=True","resource_type":"ITEM_ORDER_NOTIFY"}
|
|
On Orders Shipped (SHIP_NOTIFY) {"resource_url":"https://ssapiX.shipstation.com/shipments?storeID=123456&batchId=12345678","resource_type":"SHIP_NOTIFY"}
|
|
On Items Shipped (ITEM_SHIP_NOTIFY) {"resource_url":"https://ssapiX.shipstation.com/shipments?storeID=123456&batchId=12345678&includeShipmentItems=True","resource_type":"ITEM_SHIP_NOTIFY"}
|