🪝Webhooks

Outbound webhooks send workspace events to an endpoint you control. Each delivery is a JSON POST signed with a secret only you and Shippified know. Use them to push new orders and shipping updates into your own systems, or into tools such as n8n or Zapier, instead of polling.

Endpoints

Event types

• order is the full order object after the change.

• source is the channel: discord, email or manual.

• patch lists the fields the PATCH applied, plus status when a tracking number moved the order to shipped, and the updated userEdited. A cleared sale price appears as "salePriceCents": null.

• carrier is a carrier key: ups, fedex, usps, dhl or dhl-express. delivered is a boolean; eventCount the number of carrier scans.

One message can produce several events: a shipping email for a known order fires order.merged and then order.shipped. Repeated tracking lookups don't repeat order.shipped or order.delivered; they fire only on a real status change.

Create a subscription

You can do this in the dashboard or through the API.

• Dashboard
• curl
• TypeScript SDK
• MCP

1. Open the Developer tab

   Go to Settings → Developer and scroll to Outbound webhooks.

2. Enter your endpoint

   Type your endpoint's URL into Receiver URL, for example https://hooks.example.com/shippified.

3. Pick events

   Under Event types, tick the events you want. Order created, Order shipped and Order delivered are ticked by default. The dashboard can't change them after creation; use PATCH (see Pause, resume and edit) or create a new subscription.

4. Create it and save the secret

   Click Create subscription. The signing secret (whsec_…) is shown once: copy it into your receiver's configuration before leaving the page.

Response 201 Created:

{
  "id": "whsub_m1x2y3z4_k9d2q",
  "userId": "usr_4f1c2a9b7e0d3c11",
  "url": "https://hooks.example.com/shippified",
  "prefix": "whsec_Q2x8v1Z",
  "eventTypes": ["order.created", "order.shipped", "order.delivered"],
  "active": true,
  "failureCount": 0,
  "createdAt": "2026-09-24T15:30:00.000Z",
  "needsSecretRotation": false,
  "secret": "whsec_Q2x8v1Z…"
}

Shippified keeps the secret encrypted so it can sign deliveries across restarts and deploys; neither the encrypted value nor a hash is ever returned. Each account can have 25 subscriptions.

Subscription fields

What a delivery looks like

Every delivery is an HTTP POST with a JSON body.

Headers

Body

{
  "id": "evt_mq1a2b3c_0a1b2c3d",
  "type": "order.shipped",
  "createdAt": "2026-09-24T15:31:02.337Z",
  "userId": "usr_4f1c2a9b7e0d3c11",
  "data": {
    "order": {
      "id": "ord_mpvu9uim_aeh5t",
      "status": "shipped",
      "trackingNumber": "1Z999AA10123456784",
      "carrier": "UPS",
      "…": "…"
    },
    "source": "email"
  }
}

Verify the signature

The signature is an HMAC-SHA256 of the exact raw body:

• Key: the whole secret string, whsec_ prefix included, as UTF-8 bytes. Don't base64-decode it.

• Output: lowercase hex, prefixed with sha256=.

1. Read the raw body

   Get the body bytes before parsing JSON. Parsing and re-serialising changes the bytes and the check fails.

2. Compute the expected value

   "sha256=" + hex(HMAC_SHA256(key = secret, message = rawBody))

3. Compare in constant time

   Compare with the X-Shippified-Signature header using a timing-safe comparison.

4. Reject mismatches

   Answer 401 and do nothing else. Answer 2xx quickly for valid deliveries, and do slow work afterwards.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.SHIPPIFIED_WEBHOOK_SECRET; // "whsec_..."

function isValidSignature(rawBody, header, secret) {
  if (typeof header !== "string") return false;
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw keeps the exact bytes for this route.
app.post("/shippified", express.raw({ type: "application/json" }), (req, res) => {
  if (!isValidSignature(req.body, req.get("X-Shippified-Signature"), SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // Deduplicate on event.id, then queue the work.
  console.log(event.type, event.id);
  res.sendStatus(204);
});

app.listen(3000);

import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["SHIPPIFIED_WEBHOOK_SECRET"]  # "whsec_..."


def is_valid_signature(raw_body: bytes, header: str | None, secret: str) -> bool:
    if not header:
        return False
    expected = "sha256=" + hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)


@app.post("/shippified")
def shippified_webhook():
    raw_body = request.get_data()  # exact bytes, before any JSON parsing
    if not is_valid_signature(raw_body, request.headers.get("X-Shippified-Signature"), SECRET):
        abort(401)
    event = request.get_json()
    # Deduplicate on event["id"], then queue the work.
    print(event["type"], event["id"])
    return "", 204

import { verifyShippifiedSignature } from "shippified-sdk";

// Works in Node 18+, browsers and edge runtimes (WebCrypto).
export default {
  async fetch(request: Request, env: { SHIPPIFIED_WEBHOOK_SECRET: string }) {
    const rawBody = await request.text();
    const valid = await verifyShippifiedSignature({
      rawBody,
      header: request.headers.get("x-shippified-signature") ?? "",
      secret: env.SHIPPIFIED_WEBHOOK_SECRET,
    });
    if (!valid) return new Response("invalid signature", { status: 401 });
    const event = JSON.parse(rawBody);
    return new Response(null, { status: 204 });
  },
};

Delivery rules

• Timeout: each delivery must finish within 5 seconds, or it counts as failed (lastError: "timeout").

• Success is any 2xx. Redirects aren't followed: 3xx is a failure (HTTP 301, HTTP 302…). Use the final URL.

• No retries. Each event is sent once per subscription. A failed delivery isn't retried or queued.

• No ordering guarantee. Deliveries run concurrently, so order.shipped can arrive before the order.merged that came with it.

• Auto-pause. Each failure increments failureCount and records lastError. At 10 consecutive failures the subscription is set to active: false; the dashboard shows "Paused — auto-paused after 10 consecutive failures. Fix your receiver, then resume."

• Address check when sending. The address each connection actually goes to is checked again at send time, so a hostname that later starts resolving to a private address fails instead of reaching it.

Test a subscription

POST /api/webhook-subscriptions/:id/test sends a test event right now and returns the result. Tests don't change failureCount or lastError. In the dashboard, click Test on the subscription; it sends the subscription's first event type and shows "Receiver returned 204." or "Failed: …".

curl -s -X POST https://shippified.net/api/webhook-subscriptions/whsub_m1x2y3z4_k9d2q/test \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"eventType": "order.shipped"}'

const result = await shippified.webhookSubscriptions.test("whsub_m1x2y3z4_k9d2q", "order.shipped");
console.log(result.ok, result.status, result.error);

{ "ok": true, "status": 204 }

A test uses the normal envelope and signature, adds X-Shippified-Test: true, has an id starting evt_test_, and carries "data": { "test": true } instead of a real order. Make your handler ignore or accept test events explicitly. A failed test still returns 200, with { "ok": false, "status"?: <code>, "error": "…" }.

Pause, resume and edit

PATCH /api/webhook-subscriptions/:id changes only the fields you send, validated as on create. Sending "active": true also resets failureCount to 0, so a subscription you turn back on after an auto-pause starts clean. The dashboard's Pause / Resume button does the same.

curl -s -X PATCH https://shippified.net/api/webhook-subscriptions/whsub_m1x2y3z4_k9d2q \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": true, "eventTypes": ["order.created", "order.merged", "order.delivered"]}'

Returns the updated subscription, without secret.

Rotate the signing secret

POST /api/webhook-subscriptions/:id/rotate-secret returns the subscription with a new secret, shown once. It also resets failureCount, clears lastError, sets active: true and clears needsSecretRotation, so it's the one-step recovery for a paused subscription too. In the dashboard, click Rotate and confirm Rotate secret.

curl -s -X POST https://shippified.net/api/webhook-subscriptions/whsub_m1x2y3z4_k9d2q/rotate-secret \
  -H "Authorization: Bearer $SHIPPIFIED_API_KEY"

const rotated = await shippified.webhookSubscriptions.rotateSecret("whsub_m1x2y3z4_k9d2q");
await saveSecret(rotated.id, rotated.secret);

Subscriptions that need a new secret

Subscriptions created before Shippified started storing secrets have none, and come back with "needsSecretRotation": true:

• Their deliveries are held: events are skipped for that subscription (not queued), and the skips don't count toward auto-pause.

• The test endpoint returns { "ok": false, "error": "Signing secret unavailable — this subscription predates stored secrets. Rotate the secret to resume deliveries." }.

• The dashboard says "Deliveries are on hold: this subscription's signing secret needs to be regenerated." with a Rotate secret now button.

Rotate the secret and put the new one in your receiver. If a stored secret ever can't be decrypted on the server, deliveries are skipped the same way and lastError says to rotate.

Delete a subscription

DELETE /api/webhook-subscriptions/:id returns 200 {"ok": true} or 404. It's immediate. In the dashboard the bin button asks "Delete this webhook subscription?" and deletes on Delete subscription.

Errors

Private addresses are refused

Shippified makes requests to URLs you give it, so it refuses any URL whose hostname resolves to a private or internal address. The same check applies to webhook subscription URLs (create and PATCH), bot output webhooks (outputWebhook on /api/bots) and the workspace Discord webhooks in settings (outputWebhook, updatesWebhook on POST /api/settings).

Refused: loopback (127.0.0.0/8, ::1), private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7), link-local (169.254.0.0/16, fe80::/10), carrier-grade NAT (100.64.0.0/10), documentation, benchmarking, multicast and reserved ranges, and IPv6 forms that embed one of those IPv4 addresses. Every resolved address is checked, and again when each request is sent. Bot and settings errors are prefixed with the field name, for example outputWebhook: url cannot point at private / loopback addresses.

Troubleshooting

The public feed

Not a subscription, but the other place your orders can be posted: if your workspace has public stats turned on, each checkout that comes in through a Discord bot can be mirrored to Shippified's community feed channel. The mirrored post has only the item name, store, price and product image, always under the name Shippified; order numbers, tracking numbers, profile and customer names, emails, addresses and your bot's name are never included. Turn public stats off to stop it.