# 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](#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](#verifying-signatures)) |

### Body

Every event uses the same envelope:

```json
{
  "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](#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](orders.md) for
every field. Abbreviated:

```json
{
  "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):

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

Shipping-address change, before any label exists:

```json
{
  "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`

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

### `order.refunded`

```json
{
  "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):

```json
{
  "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`:

```json
{
  "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`

```json
{
  "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`

```json
{
  "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

```typescript
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

```typescript
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)

```typescript
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

```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](#endpoint-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 `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:

| 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](#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

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

### Response

```json
{
  "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](#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

```bash
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"]
  }'
```

```typescript
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](#rotate-the-signing-secret).

```json
{
  "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](#endpoint-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

```bash
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

```json
{
  "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

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

### Response

```json
{
  "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:

```json
{
  "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

```bash
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`.

```json
{
  "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](#endpoint-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

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

### Response

```json
{
  "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

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

### Response

```json
{
  "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.
