asyncapi: 2.6.0 info: title: ShipStation Webhooks version: '1.0.0' description: |- AsyncAPI description of the ShipStation V1 outbound webhook surface. ShipStation delivers event notifications by issuing HTTP POST requests with a JSON body to a `target_url` that the customer registers through the `POST /webhooks/subscribe` endpoint (or via the ShipStation UI under Account Settings > Integrations > Integration Partners). Every documented webhook event uses the same envelope payload shape (the `Webhook` model): a `resource_url` that the subscriber must fetch with ShipStation API Basic Authentication credentials to retrieve the triggering resource, and a `resource_type` string that names the event. Per the ShipStation API reference, the four event types in scope here are: - ORDER_NOTIFY — fires when any new order is imported, regardless of store. - ITEM_ORDER_NOTIFY — fires when a new order is imported, with the resource URL scoped to the order items. - SHIP_NOTIFY — fires when an order is shipped. - ITEM_SHIP_NOTIFY — fires when an order is shipped, with the resource URL scoped to the shipped items. Source documentation (ShipStation V1 docs, retrieved from web.archive.org snapshots of www.shipstation.com/docs/api/): - Subscribe to Webhook: /docs/api/webhooks/subscribe/ - List Webhooks: /docs/api/webhooks/list/ - Unsubscribe to Webhook: /docs/api/webhooks/unsubscribe/ - Webhook model: /docs/api/models/webhook/ Security: The HTTP POST that ShipStation sends to `target_url` does not, per the public V1 docs, include a published signing header. The documented authentication path is on the *callback* the subscriber issues back to ShipStation to dereference `resource_url`: the subscriber authenticates to `ssapi.shipstation.com` with HTTP Basic credentials (API key and secret). Subscribers commonly defend the inbound `target_url` with HTTPS plus a hard-to-guess path or embedded Basic credentials. contact: name: ShipStation API url: https://www.shipstation.com/docs/api/ license: name: ShipStation Terms of Service url: https://www.shipstation.com/legal/terms-of-service/ defaultContentType: application/json servers: subscriber: url: '{targetUrl}' protocol: https description: |- Customer-hosted HTTPS endpoint that receives webhook POSTs from ShipStation. The full URL (including path) is the `target_url` value registered with `POST /webhooks/subscribe`. variables: targetUrl: default: https://example.com/shipstation/webhook description: Fully-qualified HTTPS URL of the subscriber endpoint. channels: /shipstation/webhook: description: |- Single subscriber endpoint that receives every ShipStation webhook event for the registered subscription. ShipStation sends one event per HTTP POST. The `resource_type` field on the JSON body identifies the event class; the `resource_url` field is a fully-qualified HTTPS URL on `ssapi.shipstation.com` that the subscriber should GET (using its ShipStation Basic Auth credentials) to retrieve the resource that triggered the event. bindings: http: type: request method: POST bindingVersion: '0.3.0' publish: operationId: receiveShipStationWebhook summary: Receive a ShipStation webhook event description: |- ShipStation POSTs a `Webhook` JSON object to the subscriber endpoint when the subscribed event occurs. Subscribers should respond with a 2xx status code. To consume the event the subscriber must follow `resource_url` with an authenticated GET against the ShipStation V1 API. message: oneOf: - $ref: '#/components/messages/OrderNotify' - $ref: '#/components/messages/ItemOrderNotify' - $ref: '#/components/messages/ShipNotify' - $ref: '#/components/messages/ItemShipNotify' components: messages: OrderNotify: name: OrderNotifyEvent title: ORDER_NOTIFY summary: A new order has been imported into ShipStation. description: |- Fires when a new order is imported into ShipStation, regardless of the store it came from (unless the subscription was scoped to a specific `store_id` at subscribe time). The `resource_url` points to a listing of the imported order(s) on the V1 API. contentType: application/json bindings: http: headers: type: object properties: Content-Type: type: string const: application/json bindingVersion: '0.3.0' payload: allOf: - $ref: '#/components/schemas/WebhookEnvelope' - type: object properties: resource_type: type: string const: ORDER_NOTIFY ItemOrderNotify: name: ItemOrderNotifyEvent title: ITEM_ORDER_NOTIFY summary: A new order has been imported, scoped to the items on the order. description: |- Fires when a new order is imported into ShipStation. The `resource_url` is scoped to the items contained on the newly imported order(s). contentType: application/json bindings: http: headers: type: object properties: Content-Type: type: string const: application/json bindingVersion: '0.3.0' payload: allOf: - $ref: '#/components/schemas/WebhookEnvelope' - type: object properties: resource_type: type: string const: ITEM_ORDER_NOTIFY ShipNotify: name: ShipNotifyEvent title: SHIP_NOTIFY summary: An order has been shipped. description: |- Fires when an order is marked shipped in ShipStation (either through label creation or a manual mark-shipped action). The `resource_url` points to a listing of the shipment(s) on the V1 API. contentType: application/json bindings: http: headers: type: object properties: Content-Type: type: string const: application/json bindingVersion: '0.3.0' payload: allOf: - $ref: '#/components/schemas/WebhookEnvelope' - type: object properties: resource_type: type: string const: SHIP_NOTIFY ItemShipNotify: name: ItemShipNotifyEvent title: ITEM_SHIP_NOTIFY summary: An order has been shipped, scoped to the shipped items. description: |- Fires when an order is marked shipped in ShipStation. The `resource_url` is scoped to the items contained on the resulting shipment(s). contentType: application/json bindings: http: headers: type: object properties: Content-Type: type: string const: application/json bindingVersion: '0.3.0' payload: allOf: - $ref: '#/components/schemas/WebhookEnvelope' - type: object properties: resource_type: type: string const: ITEM_SHIP_NOTIFY schemas: WebhookEnvelope: title: Webhook description: |- Common envelope shape that ShipStation POSTs for every event, as defined by the published Webhook model in the V1 docs. type: object properties: resource_url: type: string format: uri maxLength: 200 description: |- URL to GET (with ShipStation API Basic Authentication credentials) to retrieve the resource that triggered the webhook. Limited to 200 characters by the API. resource_type: type: string description: |- The event type that triggered the webhook. One of the documented event values. enum: - ORDER_NOTIFY - ITEM_ORDER_NOTIFY - SHIP_NOTIFY - ITEM_SHIP_NOTIFY