shipstation-webhooks

ShipStation Webhooks

When to Use This Skill

• How do I receive ShipStation webhooks?
• How do I secure a ShipStation webhook endpoint when there is no signature?
• How do I fetch the resource_url from a ShipStation webhook payload?
• How do I handle ORDER_NOTIFY, SHIP_NOTIFY, or ITEM_SHIP_NOTIFY events?
• Why does my ShipStation webhook only contain a resource_url and resource_type?

How ShipStation V1 Webhooks Work

This skill targets the ShipStation V1 API (ssapi.shipstation.com), the source you connect to Hookdeck.

Two things make V1 different from most webhook providers:

1. Thin payloads. ShipStation does not send the resource data. It POSTs a small JSON body with a URL you must fetch back:

   { "resource_url": "https://ssapi.shipstation.com/orders?...", "resource_type": "ORDER_NOTIFY" }
   

   You GET resource_url with HTTP Basic auth (your API key : API secret) to get the actual orders/shipments. This authenticated fetch-back is the primary trust signal.

2. No signature. V1 has no HMAC / no signing secret — there is nothing to verify cryptographically. Protect the endpoint by putting an unguessable secret token in the target URL (https://you.com/webhooks/shipstation?token=…) and comparing it timing-safe on every request, over HTTPS. Combined with the authed fetch-back, this is the trust model.

Verification (core)

There is no signature. Verify the shared secret token from the query string (timing-safe), then fetch the real resource with Basic auth. Pass only ShipStation hosts to the fetch (SSRF guard).

const crypto = require('crypto');

// 1. Timing-safe compare of the ?token= query param against your secret
function verifyToken(provided, expected) {
  if (!provided || !expected) return false;
  const a = Buffer.from(provided);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// resource_url hosts are reportedly numbered (ssapi1/ssapi2.shipstation.com) — match a pattern, not one host
const SHIPSTATION_HOST_RE = /^ssapi\d*\.shipstation\.com$/;

// 2. Fetch the thin payload's resource_url with Basic auth (API key : API secret)
async function fetchResource(resourceUrl, key, secret) {
  if (!SHIPSTATION_HOST_RE.test(new URL(resourceUrl).hostname)) {
    throw new Error('Refusing to fetch non-ShipStation host'); // SSRF guard
  }
  const auth = Buffer.from(`${key}:${secret}`).toString('base64');
  const res = await fetch(resourceUrl, { headers: { Authorization: `Basic ${auth}` } });
  if (res.status === 429) throw new Error(`Rate limited; reset ${res.headers.get('X-Rate-Limit-Reset')}s`);
  if (!res.ok) throw new Error(`Fetch failed: ${res.status}`);
  return res.json();
}