Webhooks

ShipWave sends an HTTPS POST to your endpoint when certain things happen in your account. Each request is signed, carries a delivery ID you can use to discard duplicates, and is retried for about 12 hours if your endpoint does not accept it.

Delivery is at-least-once and unordered: the same delivery can arrive more than once, and deliveries can arrive out of order. Build your receiver to verify the signature, skip delivery IDs it has already processed, and respond quickly.


Required API Key Scopes

Managing subscriptions needs a general-purpose key. Resource scopes such as read:orders or write:shipments do not grant webhook access.

EndpointScope (any one of)
GET /api/v1/webhooksread:*, read, *
POST /api/v1/webhookswrite:*, write, *
PUT /api/v1/webhooks/:idwrite:*, write, *
DELETE /api/v1/webhooks/:idwrite:*, write, *
POST /api/v1/webhooks/:id/testwrite:*, write, *
POST /api/v1/webhooks/:id/rotate-secretwrite:*, write, *
GET /api/v1/webhooks/:id/deliveriesread:*, read, *

A key without the scope gets 403 FORBIDDEN (API key lacks required scope "write:*"). A subscription receives events for the whole account, whichever API key created it.


Events

Coverage is specific. Most events fire only for actions taken through the public API, so read the "Sent when" column before relying on an event.

EventSent whenNot sent for
order.createdPOST /api/v1/orders creates a new order (201).Orders imported from Shopify, Amazon or other connected channels, CSV imports, orders created in the dashboard, and a POST that returns an existing order (200) because externalId or Idempotency-Key matched.
order.updatedPUT /api/v1/orders/:id; DELETE /api/v1/orders/:id (cancel); a shipping-address change made through the address-change workflow, whether started by POST /api/v1/orders/:id/address-change, the ShipWave dashboard, or an address edit in Shopify.Other dashboard or channel edits, and status changes caused by fulfillment or tracking.
order.cancelledPOST /api/v1/orders/:id/cancel-or-refund cancels the order (nothing had shipped and the cancellation succeeded). Sent after the request's order.refunded.DELETE /api/v1/orders/:id (that sends order.updated), and cancellations in the dashboard or Shopify.
order.refundedPOST /api/v1/orders/:id/cancel-or-refund completes a refund.Refunds issued in the dashboard or Shopify.
shipment.createdPOST /api/v1/orders/:id/labels buys a label (one event per box), or the address-change workflow buys a replacement label.Labels bought in the dashboard, by automation rules, or through other ShipWave routes.
shipment.tracking_updatedShipWave receives a carrier tracking update for any shipment in your account, however the label was bought. A new scan can repeat the previous status.—
shipment.voidedPOST /api/v1/shipments/:id/void and the carrier accepts the void.Voids in the dashboard, automatic voids of unused labels, and the old label voided during an address change.

POST /api/v1/webhooks/:id/test sends a webhook.test event (see Send a Test Event). You cannot subscribe to it.


Delivery Format

Request

ShipWave sends POST with a JSON body to your subscription URL.

HeaderDescription
Content-Typeapplication/json
X-ShipWave-EventEvent type, e.g. shipment.created
X-ShipWave-Delivery-IdUnique ID of this delivery, e.g. whd_5f0c1e2d3c4b4a59a8f7e6d5c4b3a291. The same on every retry of the delivery. Use it to discard duplicates.
X-ShipWave-AttemptAttempt number, starting at 1
X-ShipWave-TimestampUnix time in seconds when this attempt was sent
X-ShipWave-SignatureHex HMAC-SHA256 signature of this attempt (see Verifying Signatures)

Body

Every event uses the same envelope:

{
  "id": "whd_5f0c1e2d3c4b4a59a8f7e6d5c4b3a291",
  "event": "shipment.created",
  "timestamp": "1760979600",
  "data": {
    "id": "clx2ship1",
    "trackingCode": "9400111899223100012345",
    "labelUrl": "https://easypost-files.s3.amazonaws.com/files/postage_label/20261020/label.png",
    "carrier": "USPS",
    "service": "Priority",
    "rate": 12.5
  }
}
FieldTypeDescription
idstringDelivery ID, the same value as X-ShipWave-Delivery-Id
eventstringEvent type
timestampstringUnix time in seconds when the event was queued. Unlike the X-ShipWave-Timestamp header, it does not change between attempts.
dataobjectEvent payload (see Event Payloads)

Each subscription gets its own delivery ID. If two subscriptions point at the same URL, each sends its own copy of the event.


Event Payloads

The data object for each event. Fields can be added over time; ignore ones you don't use.

order.created

The order exactly as the POST /api/v1/orders response returns it, including store, warehouse (id, name) and lineItems. See Orders for every field. Abbreviated:

{
  "id": "clx1abc2d3efg",
  "storeId": "clw9store1",
  "warehouseId": "clw9wh1",
  "externalId": "erp_12345",
  "orderNumber": "1042",
  "status": "pending",
  "customerName": "Jane Smith",
  "customerEmail": "jane@example.com",
  "shippingAddress": {
    "name": "Jane Smith",
    "street1": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "orderDate": "2026-10-20T14:30:00.000Z",
  "createdAt": "2026-10-20T14:30:00.000Z",
  "store": { "id": "clw9store1", "shopDomain": "myshop.myshopify.com", "platform": "shopify" },
  "warehouse": { "id": "clw9wh1", "name": "Main Warehouse" },
  "lineItems": [{ "id": "clx1li1", "sku": "WIDGET-1", "name": "Widget", "quantity": 2, "price": 24.99 }]
}

order.updated

The shape depends on what changed.

PUT /api/v1/orders/:id sends the updated order, as that endpoint's response returns it (the same shape as order.created, with the warehouse's address).

DELETE /api/v1/orders/:id (cancel):

{ "id": "clx1abc2d3efg", "status": "cancelled" }

Shipping-address change, before any label exists:

{
  "id": "clx1abc2d3efg",
  "orderNumber": "1042",
  "shippingAddress": {
    "name": "Jane Smith",
    "street1": "500 Congress Ave",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  }
}

Shipping-address change that replaced an existing label adds "status": "shipped", and a shipment.created event follows for the new label.

order.cancelled

{ "id": "clx1abc2d3efg", "orderNumber": "1042", "reason": "Customer changed their mind" }

order.refunded

{
  "id": "clx1abc2d3efg",
  "orderNumber": "1042",
  "refundedAmount": 44.98,
  "restockingFee": 5,
  "shopifyRefundId": "917282963",
  "cancelled": true,
  "refundScope": "full_order",
  "scopeSubtotal": 49.98,
  "selectedLineItems": [
    {
      "orderLineItemId": "clx1li1",
      "shopifyLineItemId": 14523498765,
      "sku": "WIDGET-1",
      "name": "Widget",
      "unitPrice": 24.99,
      "orderedQuantity": 2,
      "quantity": 2,
      "subtotal": 49.98
    }
  ]
}

refundScope is full_order or line_items. cancelled is true when the same request also cancelled the order; an order.cancelled event follows.

shipment.created

From POST /api/v1/orders/:id/labels, the same object as the response's shipment. A multi-box purchase sends one event per box, with boxIndex (0-based):

{
  "id": "clx2ship1",
  "trackingCode": "9400111899223100012345",
  "labelUrl": "https://easypost-files.s3.amazonaws.com/files/postage_label/20261020/label.png",
  "carrier": "USPS",
  "service": "Priority",
  "rate": 12.5,
  "boxIndex": 0,
  "orderId": "clx1abc2d3efg",
  "orderNumber": "1042"
}

From an address change that replaced the label, the shipment ID is in shipmentId instead of id:

{
  "shipmentId": "clx2ship2",
  "orderShipmentId": "clx2os2",
  "trackingCode": "9400111899223100067890",
  "carrier": "USPS",
  "service": "Priority",
  "labelUrl": "https://easypost-files.s3.amazonaws.com/files/postage_label/20261020/label2.png",
  "rate": 12.5,
  "deliveryDays": 2,
  "orderId": "clx1abc2d3efg",
  "orderNumber": "1042"
}

rate is the label price in USD that the account is charged. orderId and orderNumber identify the order the label belongs to.

shipment.tracking_updated

{
  "shipmentId": "clx2ship1",
  "trackingCode": "9400111899223100012345",
  "status": "in_transit",
  "statusDetail": "arrived_at_facility",
  "estimatedDeliveryDate": "2026-10-23T00:00:00.000Z",
  "finalized": false
}

status is the carrier status: pre_transit, in_transit, out_for_delivery, available_for_pickup, delivered, return_to_sender, failure, cancelled, error or unknown. finalized is true for delivered, return_to_sender, failure and cancelled. deliveredAt (the latest delivered scan), estimatedDeliveryDate and statusDetail are omitted when the carrier has not provided them.

shipment.voided

{
  "shipmentId": "clx2ship1",
  "refundStatus": "submitted",
  "trackingCode": "9400111899223100012345",
  "balanceRefundedCents": 0,
  "balanceRefundStatus": "pending_carrier",
  "balanceRefundHeldUntil": null,
  "balanceRefundMessage": "The carrier refund is pending. $12.50 returns to your shipping balance after the carrier confirms it (USPS usually takes 15 to 30 days) and no sooner than 7 days after the void, if the label was never scanned.",
  "balanceSettlementError": null,
  "orderStatus": "pending",
  "shopifyReconciliation": { "status": "not_applicable", "fulfillmentIds": [] }
}

orderStatus and shopifyReconciliation are present only when the shipment belongs to an order. shopifyReconciliation.status is cancelled, tracking_updated, not_applicable, not_found, failed or skipped_unconfirmed_void. balanceRefundStatus is none, credited, held, pending_carrier or not_credited.


Verifying Signatures

Every attempt is signed when it is sent, including retries.

  1. Take the X-ShipWave-Timestamp header and the raw request body, exactly as received. Do not parse and re-serialize the JSON first.
  2. Compute HMAC-SHA256 over {timestamp}.{raw_body} (the timestamp, a dot, then the body), using your webhook secret as the key.
  3. Hex-encode the result and compare it with X-ShipWave-Signature in constant time.
  4. Reject the request if the timestamp is more than 5 minutes from your clock.

Use the secret exactly as issued. It is a 64-character string. Use the string itself as the HMAC key (UTF-8 bytes). Do not hex-decode it.

Check lengths before a constant-time compare. Node's crypto.timingSafeEqual throws when the two buffers differ in length, so a missing or malformed signature would crash a handler that skips this check.

Node.js

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 300; // 5 minutes

export function verifyShipWaveSignature(
  rawBody: string,
  timestamp: string | undefined,
  signature: string | undefined,
  secret: string
): boolean {
  if (!timestamp || !signature || !/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret) // the secret string as issued, not hex-decoded
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");

  const received = Buffer.from(signature, "utf8");
  const computed = Buffer.from(expected, "utf8");
  // timingSafeEqual throws on different lengths, so check first.
  return received.length === computed.length && crypto.timingSafeEqual(received, computed);
}

Express

import express from "express";

const app = express();
const WEBHOOK_SECRET = process.env.SHIPWAVE_WEBHOOK_SECRET!;

app.post(
  "/webhooks/shipwave",
  express.raw({ type: "application/json" }), // keep the raw body for the signature
  async (req, res) => {
    const rawBody = req.body.toString("utf8");
    const valid = verifyShipWaveSignature(
      rawBody,
      req.header("x-shipwave-timestamp"),
      req.header("x-shipwave-signature"),
      WEBHOOK_SECRET
    );
    if (!valid) return res.status(401).send("Invalid signature");

    const deliveryId = req.header("x-shipwave-delivery-id")!;
    // Record the ID in a table with a unique constraint; skip it if it is already there.
    if (await alreadyProcessed(deliveryId)) return res.sendStatus(200);

    const event = JSON.parse(rawBody);
    await enqueueForProcessing(deliveryId, event); // do the real work after responding
    res.sendStatus(200);
  }
);

Next.js (App Router)

export async function POST(request: Request) {
  const rawBody = await request.text();
  const valid = verifyShipWaveSignature(
    rawBody,
    request.headers.get("x-shipwave-timestamp") ?? undefined,
    request.headers.get("x-shipwave-signature") ?? undefined,
    process.env.SHIPWAVE_WEBHOOK_SECRET!
  );
  if (!valid) return new Response("Invalid signature", { status: 401 });

  const event = JSON.parse(rawBody);
  // Dedupe on event.id, then process.
  return new Response(null, { status: 200 });
}

Python

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300

def verify_shipwave_signature(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    if not timestamp or not timestamp.isdigit() or not signature:
        return False
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(
        secret.encode("utf-8"),  # the secret string as issued, not hex-decoded
        timestamp.encode("utf-8") + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)  # safe for different lengths

Replay protection and duplicates

The 5-minute timestamp check stops an old request from being replayed later. Retries are signed fresh, so they pass it. A request can still legitimately arrive twice, for example when your endpoint processed it but answered after ShipWave's 10-second timeout. Store each X-ShipWave-Delivery-Id you process and skip repeats.


Responding, Retries and Failures

What counts as delivered

ShipWave waits 10 seconds for a response. Only a 2xx status counts as delivered; the response body is ignored. Everything else is a failed attempt:

  • a 3xx (redirects are not followed), 4xx or 5xx status
  • no response within 10 seconds
  • a connection, TLS or DNS error
  • a destination that fails the URL rules when the attempt is made

Respond with 200 as soon as you have verified and recorded the delivery, and do slow work afterwards.

Retry schedule

AttemptWhen
1Immediately after the event, normally within a few seconds
2–25At the delivery worker's next run after a short wait. The worker runs every 30 minutes, at :07 and :37 past the hour (UTC). The wait grows from 5 seconds to about 17 minutes, always less than the time between runs, so in practice a failed delivery is retried about every 30 minutes.

A delivery is tried at most 25 times, about 12 hours in total. After the 25th failure it is marked failed and is not sent again.

During an outage, each worker run stops sending to a subscription after 3 consecutive failed attempts. Its other deliveries wait for a later run without using up attempts, and go out oldest first once the endpoint accepts deliveries again.

Ordering

Deliveries are not guaranteed to arrive in order. Retries and the outage limit above can reorder them. When order matters, compare the body timestamp or fetch the current state from the API.

Automatic disabling

ShipWave disables a subscription only when one of its deliveries has failed all 25 attempts and your endpoint has not accepted any delivery since that delivery was queued, which means about 12 hours with no successful delivery. A short outage or a burst of failures does not disable it, and neither does one payload your endpoint keeps rejecting, as long as it accepts other deliveries in that time.

When a subscription is disabled:

  • its isActive becomes false;
  • deliveries still waiting are marked failed and are not sent;
  • events that happen while it is disabled are not queued;
  • ShipWave emails the account's email address with the endpoint, the last error, and how to turn it back on.

To turn it back on after fixing your endpoint, check it with POST /api/v1/webhooks/:id/test, then send PUT /api/v1/webhooks/:id with {"isActive": true}. This resets failureCount. Deliveries that already failed are not resent, and there is no resend endpoint. List them with GET /api/v1/webhooks/:id/deliveries?status=failed, and use GET /api/v1/orders and GET /api/v1/shipments to catch up on what you missed.

Monitoring a subscription

GET /api/v1/webhooks returns these fields for each subscription:

FieldDescription
isActivefalse when disabled by you or automatically
failureCountFailed attempts since the last successful delivery. Informational: a high count alone does not disable the subscription.
lastSentAtTime of the last successful delivery
lastErrorLast failure, e.g. HTTP 503 or Timed out after 10s. Cleared by a successful delivery.
lastErrorAtTime of the last failure

For individual deliveries, use List Deliveries.


Endpoint URL Rules

ShipWave checks the URL when you create or update a subscription, and again before every attempt. The URL must:

  • be a valid absolute URL using https:// (any port);
  • not contain a username or password (https://user:pass@... is refused);
  • use a fully qualified public hostname or a public IP address. These are refused: localhost, single-label names such as intranet, names ending in .localhost, .local, .internal, .localdomain, .home.arpa or .ts.net, cloud metadata hosts, and private, loopback, link-local, carrier-grade NAT (100.64.0.0/10), multicast, documentation and other reserved IPv4 and IPv6 ranges.

Before each attempt ShipWave resolves the hostname. If any address it resolves to is private or reserved, or the name does not resolve, the attempt fails with Webhook destination blocked: ... and is retried like any other failure. Redirects are never followed.


List Webhook Subscriptions

GET /api/v1/webhooks

Returns all webhook subscriptions for your account, newest first. The secret is not included.

If you send orders to a supplier by webhook, ShipWave manages that supplier's endpoint itself. Those system subscriptions are not listed here, and the webhook endpoints return 404 for them.

Example

curl https://shipwave.app/api/v1/webhooks \
  -H "Authorization: Bearer sw_live_abc123..."

Response

{
  "data": [
    {
      "id": "clx4wh1",
      "url": "https://myapp.com/webhooks/shipwave",
      "events": ["order.created", "shipment.created"],
      "isActive": true,
      "failureCount": 0,
      "lastSentAt": "2026-10-20T20:00:00.000Z",
      "lastErrorAt": null,
      "lastError": null,
      "createdAt": "2026-10-01T12:00:00.000Z",
      "updatedAt": "2026-10-20T20:00:00.000Z"
    }
  ]
}

Create Webhook Subscription

POST /api/v1/webhooks

Request Body

FieldTypeRequiredDescription
urlstringyesEndpoint URL; see Endpoint URL Rules
eventsstring[]yesOne or more of order.created, order.updated, order.cancelled, order.refunded, shipment.created, shipment.tracking_updated, shipment.voided

Example

curl -X POST https://shipwave.app/api/v1/webhooks \
  -H "Authorization: Bearer sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/shipwave",
    "events": ["order.created", "shipment.created", "shipment.tracking_updated"]
  }'
const res = await fetch("https://shipwave.app/api/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: "Bearer sw_live_abc123...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://myapp.com/webhooks/shipwave",
    events: ["order.created", "shipment.created", "shipment.tracking_updated"],
  }),
});
const { data } = await res.json(); // 201 Created

Response (201 Created)

The secret is included only in this response. Store it securely; it cannot be retrieved later. To replace it, use Rotate the Signing Secret.

{
  "data": {
    "id": "clx4wh1",
    "url": "https://myapp.com/webhooks/shipwave",
    "events": ["order.created", "shipment.created", "shipment.tracking_updated"],
    "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "isActive": true,
    "createdAt": "2026-10-20T10:00:00.000Z"
  }
}

Errors

StatusCodeCause
400VALIDATION_ERRORInvalid body, URL that breaks the URL rules, empty events, or an unknown event type
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key lacks the write:* scope

Update Webhook Subscription

PUT /api/v1/webhooks/:id

Updatable Fields

FieldTypeDescription
urlstringNew endpoint URL
eventsstring[]Replacement list of event types (non-empty)
isActivebooleanfalse pauses the subscription; true turns it back on and resets failureCount

Example

curl -X PUT https://shipwave.app/api/v1/webhooks/clx4wh1 \
  -H "Authorization: Bearer sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["order.created", "order.updated", "order.cancelled", "shipment.created", "shipment.voided"],
    "isActive": true
  }'

Response

{
  "data": {
    "id": "clx4wh1",
    "url": "https://myapp.com/webhooks/shipwave",
    "events": ["order.created", "order.updated", "order.cancelled", "shipment.created", "shipment.voided"],
    "isActive": true,
    "failureCount": 0,
    "lastSentAt": "2026-10-20T20:00:00.000Z",
    "updatedAt": "2026-10-20T21:00:00.000Z"
  }
}

Errors

StatusCodeCause
400VALIDATION_ERRORInvalid URL or events, or a non-boolean isActive
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key lacks the write:* scope
404NOT_FOUNDNo subscription with this ID in your account. A subscription that belongs to another account also returns 404.

Delete Webhook Subscription

DELETE /api/v1/webhooks/:id

Permanently deletes a webhook subscription and its queued deliveries. Nothing more is sent to it.

Example

curl -X DELETE https://shipwave.app/api/v1/webhooks/clx4wh1 \
  -H "Authorization: Bearer sw_live_abc123..."

Response

{
  "data": {
    "id": "clx4wh1",
    "deleted": true
  }
}

Errors

StatusCodeCause
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key lacks the write:* scope
404NOT_FOUNDNo subscription with this ID in your account. A subscription that belongs to another account also returns 404.

Send a Test Event

POST /api/v1/webhooks/:id/test

Sends one signed webhook.test event to the subscription's URL right away and returns your endpoint's answer. It uses the same headers and signature as real deliveries. The test is not queued or retried and does not change failureCount, lastSentAt or lastError. It also works on a disabled subscription, so you can check a fixed endpoint before turning it back on.

The request body sent to your endpoint:

{
  "id": "whd_8a1f0c2e9b7d4e6fa3c5b1d2e4f60718",
  "event": "webhook.test",
  "timestamp": "1760979600",
  "data": {
    "subscriptionId": "clx4wh1",
    "message": "ShipWave webhook test. Verify the signature and respond with any 2xx status."
  }
}

Example

curl -X POST https://shipwave.app/api/v1/webhooks/clx4wh1/test \
  -H "Authorization: Bearer sw_live_abc123..."

Response

The API call returns 200 whatever your endpoint answered. Check delivered.

{
  "data": {
    "deliveryId": "whd_8a1f0c2e9b7d4e6fa3c5b1d2e4f60718",
    "event": "webhook.test",
    "delivered": false,
    "statusCode": 401,
    "error": "HTTP 401",
    "durationMs": 184
  }
}

statusCode is null when there was no HTTP response (timeout, connection error, or a destination blocked by the URL rules).

Errors

StatusCodeCause
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key lacks the write:* scope
404NOT_FOUNDNo subscription with this ID in your account

Rotate the Signing Secret

POST /api/v1/webhooks/:id/rotate-secret

Replaces the subscription's secret and returns the new one. This is the only time the new secret is shown. Every attempt after the rotation, including retries of deliveries already queued, is signed with the new secret. There is no period where ShipWave signs with both. To rotate without rejecting deliveries, deploy a receiver that accepts a signature made with either the old or the new secret, rotate, store the new secret, then remove the old one.

Example

curl -X POST https://shipwave.app/api/v1/webhooks/clx4wh1/rotate-secret \
  -H "Authorization: Bearer sw_live_abc123..."

Response

{
  "data": {
    "id": "clx4wh1",
    "url": "https://myapp.com/webhooks/shipwave",
    "events": ["order.created", "shipment.created"],
    "secret": "9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0",
    "isActive": true,
    "updatedAt": "2026-10-20T22:00:00.000Z"
  }
}

Errors

StatusCodeCause
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key lacks the write:* scope
404NOT_FOUNDNo subscription with this ID in your account

List Deliveries

GET /api/v1/webhooks/:id/deliveries

Returns the subscription's deliveries, newest first, with their status and last error. Payloads are not included. Delivery records are kept until you delete the subscription.

Query Parameters

ParameterTypeDefaultDescription
statusstringallpending (waiting for a retry), processing (being sent), delivered or failed
pageinteger1Page number
limitinteger50Results per page (1–100)

Example

curl "https://shipwave.app/api/v1/webhooks/clx4wh1/deliveries?status=failed&limit=20" \
  -H "Authorization: Bearer sw_live_abc123..."

Response

{
  "data": [
    {
      "id": "whd_5f0c1e2d3c4b4a59a8f7e6d5c4b3a291",
      "event": "shipment.created",
      "status": "pending",
      "attempts": 3,
      "lastError": "HTTP 503",
      "nextAttemptAt": "2026-10-20T13:07:10.000Z",
      "deliveredAt": null,
      "createdAt": "2026-10-20T12:00:02.000Z",
      "updatedAt": "2026-10-20T12:37:04.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

id is the same value as the X-ShipWave-Delivery-Id header and the body id. nextAttemptAt is the earliest time of the next retry and is null unless the status is pending; the retry goes out at the first worker run after it.

Errors

StatusCodeCause
400VALIDATION_ERRORUnknown status
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key lacks the read:* scope
404NOT_FOUNDNo subscription with this ID in your account

Not Available

There is no endpoint to resend a delivery or to fetch a delivery's payload, and no period where ShipWave signs with two secrets at once.

Webhooks — API Documentation | ShipWave