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 3rd party system that wants to pull data from ShipStation, it may be beneficial for you to set up webhooks so ShipStation can push alerts when certain events occur in your account. These alerts will help guide the system to an endpoint which 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 the ShipStation account. When triggered, ShipStation will make an API POST call to deliver a payload of data to the target URL which 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.
There are 4 types of webhooks you can create in ShipStation:
On New Orders (ORDER_NOTIFY)
On New Items (ITEM_ORDER_NOTIFY)
On Orders Shipped (SHIP_NOTIFY)
On Items Shipped (ITEM_SHIP_NOTIFY)
The On New Orders and On New Items webhook types relate to order data. These webhooks are triggered 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 are triggered when a new outbound shipping label is generated for an order. The webhooks will not be triggered for fulfillments - either through a fulfillment partner like FBA/Shipwire or fulfillments created 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.
You can create new webhooks in your ShipStation account in two different ways:
API Calls
ShipStation Account Settings
This section goes over how to generate webhooks through the ShipStation Settings page. For information on using API calls, see our in-depth API documentation for more details on creating webhooks.
To create a webhook within ShipStation:
-
Select webhooks from the set of options.
Note
If you do not already have any webhooks created, the option will be grey.
-
Click Add a Webhook.
-
Set the Name (max 100 characters), Type, whether the webhook applies to all stores or a specific store, and the target URL (max 200 characters).
Click Save to create the webhook after the details have been entered.
You can removed existing webhooks in your ShipStation account in two different ways:
API Calls
ShipStation Account Settings
This section goes over how to removes 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. Will not be included if webhook effects 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"}
|