If you're using ShipStation's REST API to communicate order information, or if you're using a third-party system that pulls data from ShipStation, it may be beneficial for you to set up webhooks for ShipStation to 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.
This article covers the following topics:
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. This will include a follow-up resource_url 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.
ShipStation offers four types of webhooks to create:
- 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 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 fulfillments - either through a fulfillment partner like FBA/Shipwire or one 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.
There are two different ways to create new webhooks in your ShipStation account:
- API Calls
- In Settings > Integration Partners > Webhooks
This article 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:
1. Go to your Account Settings (the wrench icon in the upper right).
2. Select Integrations and then Integration Partners from the left-hand sidebar.
3. Select webhooks from the set of options.
NOTE: If you do not already have any webhooks created, the option will be grey.
4. Click Add a Webhook.
Alternatively, if the webhook has already been created and needs to be updated, you can update it with the Edit action, or delete it with the Remove action.
5. Set the Name (max 100 characters) and Type, enter the target URL (max 200 characters), then define whether the webhook applies to all stores or a specific store.
6. Click Save to create the webhook after you have entered these details.
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 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 (for
- 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.
Examples of webhook payloads:
On New Orders
On New Items
On Orders Shipped
ee4On Items Shipped