Waybridge API | Version 1.0.0

Build with the Waybridge API

Connect shipment operations to your own systems. This guide covers the API conventions, authentication, events, and every documented endpoint.

Open live SwaggerInteractive reference for the configured backend

API base path

Routes use /api on the backend origin.

Authentication

Short-lived bearer access tokens with HttpOnly refresh sessions.

Webhook events

Signed deliveries, observable attempts, and explicit retries.

Quick start

Set your backend origin, then append the route path shown below.BACKEND_API_URLis configured as the API base ending in /api; the route examples already include that prefix.

1Choose the backend origin

For example, localhost:5000 or your deployed backend host.

2Use JSON requests

Send Content-Type: application/json for JSON request bodies. The maximum body size is 1 MiB.

3Authenticate private calls

Add the access token as a bearer token. Public tracking does not need an account.

Public tracking request

curl https://<backend-host>/api/tracking/TRK-12345

Create a shipment

curl --request POST https://<backend-host>/api/shipments \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  --data '{"origin":"London","destination":"Paris","amount":42.5}'

Authentication and access

Registration and login issue a 15-minute access token. Send it in the Authorization: Bearer header for protected operations.

Access and refresh

Keep access tokens short-lived and let the backend manage refresh sessions in an HttpOnly cookie.

Registration returns the access token as data.token. Login and refresh return data.accessToken and a compatible data.token alias. The refresh token itself is never returned in JSON. Browser clients must send credentialed requests to the configured CORS origin when refreshing.

Roles and ownership

Public registration always creates a customer account.

Customers can access their own shipments, webhooks, and delivery summaries. Admin-only operations are marked in the endpoint reference. A resource outside a customer's ownership may be reported as not found.

Refresh cookies are scoped to /api/auth and last 30 days. Outside production the cookie is named refreshToken; production HTTPS uses __Secure-refreshToken. The default SameSite policy is Strict.

Responses, pagination, and limits

Successful responses use a consistent envelope. List operations return page metadata and resource arrays under data.

Response shape

Read the envelope before the resource data.

{
  "success": true,
  "message": "Shipment retrieved",
  "data": { "...": "..." }
}

Errors use success: false, a message, and data: null. Validation errors also include an errors array with field and message details.

Paginated data includes items, a resource-named array alias, and pagination with page, limit, total, totalItems, and totalPages.

Pagination defaults

Pages are one-based. Limits vary by resource.

Default and maximum page limits by API resource
Resource	Default	Maximum
Shipments	20	100
Webhooks	10	50
Events	20	100
Deliveries	10	100
Demo receiver	20	50

Request size

JSON request bodies are limited to 1 MiB. Larger bodies return 413.

Rate limits

Authentication: 20 requests per IP per 15 minutes. Public tracking: 60 per IP per 15 minutes.

HTTP errors

Expect 400 for invalid input, 401 for missing/invalid auth, 403 for role restrictions, 404 for unavailable resources, 413 for oversized bodies, 429 when rate limited, and 500 for unexpected server errors.

Shipment lifecycle and event types

Status updates are validated transitions. A successful change appends shipment history, creates the corresponding event, and queues matching webhook deliveries.

Supported statuses

Delivered and cancelled are terminal states.

createdpicked_upin_transitarrived_at_hubout_for_deliverydelivereddelivery_failedcancelled

Allowed transitions: created → picked_up or cancelled; picked_up → in_transit or cancelled; in_transit → arrived_at_hub or cancelled; arrived_at_hub → in_transit, out_for_delivery, or cancelled; out_for_delivery → delivered or delivery_failed; and delivery_failed → out_for_delivery or cancelled. Delivered and cancelled are terminal.

Webhook event types are shipment.created, shipment.picked_up, shipment.in_transit, shipment.arrived_at_hub, shipment.out_for_delivery, shipment.delivered, shipment.delivery_failed, shipment.cancelled, and webhook.test.

Receiving signed webhooks

Each delivery is a JSON POST containing an event envelope. Verify its signature against the exact raw request body before parsing or trusting the payload.

Payload and signature

The signing secret is shown in full only when a webhook is created or its secret is regenerated.

{
  "id": "evt_123456",
  "type": "shipment.created",
  "createdAt": "2026-10-03T10:00:00.000Z",
  "data": { "...": "event-specific payload" }
}

Verify X-Webhook-Signature as sha256=<hex HMAC-SHA256> over <X-Webhook-Timestamp>.<exact raw body>, using the webhook secret. Compare digests in constant time.

The request also includes X-Webhook-Timestamp, X-Webhook-Event, and X-Webhook-Delivery. Timestamped receiver verification allows at most five minutes of clock skew.

Retries and receiver requirements

Delivery attempts run asynchronously after an event is emitted.

Any 2xx response succeeds. Automatic delivery makes at most three attempts with 2-second and 5-second retry delays; each request times out after 5 seconds. Captured receiver response text is limited to 1,000 characters.

Webhook URLs must use HTTP or HTTPS and cannot include URL credentials. Production requires HTTPS and blocks private, loopback, link-local, and reserved IP addresses after DNS resolution. Exact localhost is permitted only in development when ALLOW_LOCALHOST_WEBHOOKS and ENABLE_DEMO_RECEIVER are enabled; other loopback aliases remain blocked. Configure responses to POST /api/webhooks/{id}/test and POST /api/deliveries/{id}/resend confirm that work was queued, not that delivery succeeded.

Endpoint reference

36 operations across health, authentication, shipment management, tracking, event history, webhooks, deliveries, and the demo receiver. Request and response schemas are available in the live Swagger UI.

Health

3 operations

Public checks for confirming that the API process is responding.

MethodPathAccess and behavior

GET/

Public

Returns a lightweight response when the API is running.

GET/health

Public

Returns the API health status.

GET/api/health

Public

Compatibility alias for the health check.

Authentication

6 operations

Registration and sign-in issue short-lived access tokens and establish a server-managed refresh session.

MethodPathAccess and behavior

POST/api/auth/register

Public

Creates a customer account from name, email, and password. Registration always assigns the customer role, returns data.token, and sets an HttpOnly refresh cookie.

POST/api/auth/login

Public

Signs in with email and password, returning data.accessToken and its data.token alias, and setting an HttpOnly refresh cookie.

POST/api/auth/refresh

Refresh cookie

Rotates the refresh session cookie and issues a new access token. Send the cookie with credentials; do not put a refresh token in JSON.

POST/api/auth/logout

Public

Revokes the current refresh session when present and clears the browser cookie.

POST/api/auth/change-password

Bearer token

Changes the current user's password using currentPassword and newPassword. A successful change revokes all refresh sessions and requires signing in again.

GET/api/auth/me

Bearer token

Returns the authenticated user's public profile.

Shipments

5 operations

Create shipments, manage their ownership, and advance them through the supported delivery lifecycle.

MethodPathAccess and behavior

GET/api/shipments

Bearer token

Lists shipments visible to the caller. Customers see their assigned shipments; admins see all. Supports page, limit, search, and status filters.

POST/api/shipments

Bearer token

Creates a shipment from origin, destination, and amount. Admins also supply customer and may supply customerId; customer callers must omit customerId. Tracking numbers are generated by the API.

GET/api/shipments/{id}

Bearer token

Returns shipment details. Customers can read only shipments assigned to them; admins can read any shipment.

PATCH/api/shipments/{id}/customer

Admin only

Assigns the shipment to an existing customer using a customerId request field.

PATCH/api/shipments/{id}/status

Admin only

Advances the shipment using a status and optional note. Valid transitions append history, emit an event, and queue matching webhooks.

Tracking

1 operations

Public tracking is intended for customers checking progress without creating an account.

MethodPathAccess and behavior

GET/api/tracking/{trackingNumber}

Public

Returns the shipment status and timeline. Tracking numbers use the TRK- plus five digits format; limited to 60 requests per IP per 15 minutes.

Events

2 operations

Admin event history for shipment changes and webhook test events.

MethodPathAccess and behavior

GET/api/events

Admin only

Lists events newest-first. Supports page, limit, type, and public event ID search.

GET/api/events/{id}

Admin only

Returns an event by MongoDB ObjectId or public ID such as evt_123456.

Webhooks

8 operations

Subscribe HTTPS endpoints to shipment events. Customers manage their own hooks; admins can inspect all hooks.

MethodPathAccess and behavior

GET/api/webhooks

Bearer token

Lists visible webhooks with masked secrets. Supports page, limit, search, active/isActive, and event filters.

POST/api/webhooks

Bearer token

Creates a webhook from name, URL, and one or more event types, with optional active state. The full signing secret is returned only in this response.

GET/api/webhooks/{id}

Bearer token

Returns a webhook visible to the caller. The signing secret is masked.

PATCH/api/webhooks/{id}

Bearer token

Partially updates a visible webhook using name, url, events, or active/isActive. Set regenerateSecret to true to rotate its secret; the replacement is returned once.

PUT/api/webhooks/{id}

Bearer token

Compatibility alias with the same partial-update behavior as PATCH.

DELETE/api/webhooks/{id}

Bearer token

Deletes a webhook owned by the caller; admins can delete any webhook.

GET/api/webhooks/{id}/deliveries

Bearer token

Lists delivery summaries for a webhook visible to the caller.

POST/api/webhooks/{id}/test

Bearer token

Queues a one-off webhook.test delivery. The response confirms the work was queued, not that the receiver accepted it.

Deliveries

4 operations

Inspect webhook delivery outcomes and attempt history, or queue another attempt.

MethodPathAccess and behavior

GET/api/deliveries

Bearer token

Lists delivery summaries visible to the caller. Supports page, limit, status, webhookId, and eventId filters.

GET/api/deliveries/{id}

Bearer token

Returns a delivery summary and ordered attempt history. Accepts a summary ID or historical attempt ID.

POST/api/deliveries/{id}/resend

Bearer token

Queues another attempt for a visible delivery. The response does not wait for the receiver.

POST/api/deliveries/{id}/retry

Bearer token

Compatibility alias for POST /api/deliveries/{id}/resend.

Demo Receiver

7 operations

A test webhook destination with an optional success/failure profile. These routes are not mounted in production unless ENABLE_DEMO_RECEIVER=true.

MethodPathAccess and behavior

POST/api/demo-receiver

Public

Records an incoming JSON webhook and verifies an optional signature. Default response is 201; limited to 1,200 POST requests per IP per 15 minutes.

GET/api/demo-receiver

Admin only

Lists recorded requests with page, limit, signatureValid, and event filters. In-memory history retains at most 100 requests.

DELETE/api/demo-receiver

Admin only

Clears the recorded request history.

POST/api/demo-receiver/fail

Public

Uses the configured failure profile; the default is HTTP 500, but admins can configure a 4xx/5xx status and response body.

GET/api/demo-receiver/config

Admin only

Returns the current success and failure response profiles. Profiles reset when the backend restarts.

PATCH/api/demo-receiver/config

Admin only

Updates a success and/or failure statusCode and body. Success codes must be 200-299; failure codes must be 400-599.

DELETE/api/demo-receiver/config

Admin only

Restores the default response profiles.

Explore the interactive contract

Use Swagger to inspect full request schemas, response examples, and try operations against the live backend.

Live Swagger About Waybridge