Agent skill

ShipBob Webhooks Skill

Receive and verify ShipBob webhooks. Use when setting up ShipBob webhook handlers, debugging signature verification, or handling fulfillment events like order.shipped, order.shipment.delivered, order.shipment.tracking.updated, return.created, wro.created, or billing.charge.created.

Install this skill

npx skills add hookdeck/webhook-skills --skill shipbob-webhooks

When to Use This Skill

Setting up ShipBob webhook handlers
Debugging ShipBob signature verification failures
Understanding ShipBob event types (topics) and payloads
Handling fulfillment, shipment, return, receiving (WRO), or billing events

Verification (core)

ShipBob signs webhooks with the Standard Webhooks scheme (the same fields Svix uses). It sends three headers — webhook-id, webhook-timestamp, and webhook-signature — and the event topic in a separate x-webhook-topic header (e.g. order.shipped).

The signature is HMAC-SHA256(secret, "{webhook-id}.{webhook-timestamp}.{body}"), base64-encoded. The signing secret is whsec_<base64> — strip the whsec_ prefix and base64-decode the remainder to get the raw HMAC key. Always verify against the raw, unmodified request body (don't JSON.parse first). webhook-signature holds space-delimited versioned signatures (v1,<sig>); compare against the v1 entry with a timing-safe comparison.

Node (via the standardwebhooks package, which handles the secret decode and multi-signature parsing for you):

const { Webhook } = require('standardwebhooks');

const wh = new Webhook(process.env.SHIPBOB_WEBHOOK_SECRET); // whsec_...
// rawBody is a Buffer/string; headers use the Standard Webhooks names
const event = wh.verify(rawBody, {
  'webhook-id': req.headers['webhook-id'],
  'webhook-timestamp': req.headers['webhook-timestamp'],
  'webhook-signature': req.headers['webhook-signature'],
}); // throws WebhookVerificationError on tampering or a stale timestamp
const topic = req.headers['x-webhook-topic']; // e.g. "order.shipped"

Python (manual — there is no official ShipBob SDK):

import hmac, hashlib, base64

def verify(body: bytes, webhook_id, webhook_timestamp, webhook_signature, secret):
    signed = f"{webhook_id}.{webhook_timestamp}.{body.decode()}".encode()
    key = base64.b64decode(secret.split("_", 1)[1])  # strip 'whsec_' then base64-decode
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    sent = [s.split(",", 1)[1] for s in webhook_signature.split(" ") if "," in s]
    return any(hmac.compare_digest(expected, s) for s in sent)  # timing-safe

For complete handlers with route wiring, event dispatch, and tests, see:
examples/express/
examples/nextjs/
examples/fastapi/

Common Event Types

The topic arrives in the x-webhook-topic header (current API uses dotted names; legacy 1.0/2.0 used underscores like order_shipped).

Topic	Triggered When	Read scope
`order.shipped`	An order's shipment ships	`orders_read` / `fulfillments_read`
`order.shipment.delivered`	A shipment is delivered	`orders_read` / `fulfillments_read`
`order.shipment.tracking.updated`	Tracking info changes	`orders_read` / `fulfillments_read`
`order.shipment.exception`	A shipment hits an exception	`orders_read` / `fulfillments_read`
`return.created`	A return is created	`returns_read`
`wro.created`	A Warehouse Receiving Order is created	`receiving_read`
`billing.charge.created`	A billing charge is created	`billing_read`

For the full topic list, see ShipBob's webhook documentation.

Environment Variables

SHIPBOB_WEBHOOK_SECRET=whsec_xxxxx   # Signing secret from the webhook subscription

Subscribing

Subscribe via the API with POST /2026-01/webhook and a body of { "topics": ["order.shipped", ...], "url": "https://your.app/webhooks/shipbob" }. Requires the webhooks_write scope plus the read scope for each topic (see the table above). See references/setup.md for details.

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 shipbob --path /webhooks/shipbob

Reference Materials

references/overview.md - ShipBob webhook concepts and topics
references/setup.md - Subscribing and getting the signing secret
references/verification.md - Signature verification details and gotchas