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.
| Endpoint | Scope (any one of) |
|---|---|
GET /api/v1/webhooks | read:*, read, * |
POST /api/v1/webhooks | write:*, write, * |
PUT /api/v1/webhooks/:id | write:*, write, * |
DELETE /api/v1/webhooks/:id | write:*, write, * |
POST /api/v1/webhooks/:id/test | write:*, write, * |
POST /api/v1/webhooks/:id/rotate-secret | write:*, write, * |
GET /api/v1/webhooks/:id/deliveries | read:*, 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.
| Event | Sent when | Not sent for |
|---|---|---|
order.created | POST /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.updated | PUT /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.cancelled | POST /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.refunded | POST /api/v1/orders/:id/cancel-or-refund completes a refund. | Refunds issued in the dashboard or Shopify. |
shipment.created | POST /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_updated | ShipWave 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.voided | POST /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.
| Header | Description |
|---|---|
Content-Type | application/json |
X-ShipWave-Event | Event type, e.g. shipment.created |
X-ShipWave-Delivery-Id | Unique ID of this delivery, e.g. whd_5f0c1e2d3c4b4a59a8f7e6d5c4b3a291. The same on every retry of the delivery. Use it to discard duplicates. |
X-ShipWave-Attempt | Attempt number, starting at 1 |
X-ShipWave-Timestamp | Unix time in seconds when this attempt was sent |
X-ShipWave-Signature | Hex 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
}
}
| Field | Type | Description |
|---|---|---|
id | string | Delivery ID, the same value as X-ShipWave-Delivery-Id |
event | string | Event type |
timestamp | string | Unix time in seconds when the event was queued. Unlike the X-ShipWave-Timestamp header, it does not change between attempts. |
data | object | Event 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.
- Take the
X-ShipWave-Timestampheader and the raw request body, exactly as received. Do not parse and re-serialize the JSON first. - Compute HMAC-SHA256 over
{timestamp}.{raw_body}(the timestamp, a dot, then the body), using your webhook secret as the key. - Hex-encode the result and compare it with
X-ShipWave-Signaturein constant time. - 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
| Attempt | When |
|---|---|
| 1 | Immediately after the event, normally within a few seconds |
| 2–25 | At 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
isActivebecomesfalse; - 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:
| Field | Description |
|---|---|
isActive | false when disabled by you or automatically |
failureCount | Failed attempts since the last successful delivery. Informational: a high count alone does not disable the subscription. |
lastSentAt | Time of the last successful delivery |
lastError | Last failure, e.g. HTTP 503 or Timed out after 10s. Cleared by a successful delivery. |
lastErrorAt | Time 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 asintranet, names ending in.localhost,.local,.internal,.localdomain,.home.arpaor.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
| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | Endpoint URL; see Endpoint URL Rules |
events | string[] | yes | One 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
| Status | Code | Cause |
|---|---|---|
| 400 | VALIDATION_ERROR | Invalid body, URL that breaks the URL rules, empty events, or an unknown event type |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | API key lacks the write:* scope |
Update Webhook Subscription
PUT /api/v1/webhooks/:id
Updatable Fields
| Field | Type | Description |
|---|---|---|
url | string | New endpoint URL |
events | string[] | Replacement list of event types (non-empty) |
isActive | boolean | false 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
| Status | Code | Cause |
|---|---|---|
| 400 | VALIDATION_ERROR | Invalid URL or events, or a non-boolean isActive |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | API key lacks the write:* scope |
| 404 | NOT_FOUND | No 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
| Status | Code | Cause |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | API key lacks the write:* scope |
| 404 | NOT_FOUND | No 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
| Status | Code | Cause |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | API key lacks the write:* scope |
| 404 | NOT_FOUND | No 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
| Status | Code | Cause |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | API key lacks the write:* scope |
| 404 | NOT_FOUND | No 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
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | all | pending (waiting for a retry), processing (being sent), delivered or failed |
page | integer | 1 | Page number |
limit | integer | 50 | Results 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
| Status | Code | Cause |
|---|---|---|
| 400 | VALIDATION_ERROR | Unknown status |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | API key lacks the read:* scope |
| 404 | NOT_FOUND | No 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.