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.
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 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 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
- 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:
Go to your Account Settings (the wrench icon in the upper right).
Next, select Integrations and then Integration Partners.
Select webhooks from the set of options.
If you do not already have any webhooks created, the option will be grey.
Click the Add a Webhook action.
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.
When adding a webhook, you'll be able to set the Name, Type, whether the webhook applies to all stores or a specific store, and the target URL.
Click Save to create the webhook after the details have been entered.
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
On Items Shipped