Webhooks

Category: Public Base URL: /webhooks/cartrover Authentication: Mixed Routes: 5 routes documented

Overview#

This section documents 5 API routes for webhooks.

Quick Reference#

POST Webhooks Cartrover#

Endpoint: POST /webhooks/cartrover Authentication: Public (Optional)

Description#

CartRover (Extensiv Integration Manager) Webhook Handler — order_update ========================================================================== CartRover posts an order_update event ("Order Shipped by Warehouse") carrying the same response-style shipment object documented for GET /v1/cart/orders/status/{CUST_REF} (carrier, tracking_no, cust_ref, order_status). CONTRACT: this endpoint MUST answer HTTP 200 or CartRover retries up to 10x with exponential backoff (and may eventually disable the webhook). Rollout: CAPTURE-FIRST (mirrors src/api/webhooks/quickbox/route.ts). CARTROVER_WEBHOOK_RECORD_ENABLED (default false) gates whether we ACT on the webhook. Until a real payload/auth scheme is confirmed, this route runs in CAPTURE mode: capture the full body BEFORE any validation, never reject, always return 200. Auth: CartRover uses Basic auth / a shared credential for its own API; no documented request-signing scheme for outbound webhooks was found in the Postman collection. No raw-body middleware is registered for this route (see src/api/middlewares.ts's quickbox/resend/etc. entries for the pattern to add if a body-signature scheme is confirmed later — that middleware registration is out of this track's scope). We do NOT call process-fulfillment directly here — emit an event and let the subscriber (cartrover-shipment-status.ts) do the work, mirroring the QuickBox webhook -> event bus -> subscriber -> process-fulfillment chain.

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success (200):

{
  received,
  mode,
}

Also returns (200):

{
  received,
  mode,
  routed,
}

Also returns (200):

{
  received,
  mode,
}

Also returns (200):

{
  received,
  mode,
  routed,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/webhooks/cartrover' \
  -H 'Content-Type: application/json'

POST Webhooks Quickbox#

Endpoint: POST /webhooks/quickbox Authentication: Public (Optional)

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success (200):

{
  received,
  mode,
  signature_checked,
  signature_valid,
}

Also returns (200):

{
  received,
  mode,
}

Error (401):

{
  error,
}

Error (500):

{
  error,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/webhooks/quickbox' \
  -H 'Content-Type: application/json'

POST Webhooks Resend#

Endpoint: POST /webhooks/resend Authentication: Public (Optional)

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success (200):

{
  received,
  mode,
}

Also returns (200):

{
  received,
  handled,
}

Also returns (200):

{
  received,
  correlated,
}

Also returns (200):

{
  received,
  duplicate,
}

Also returns (200):

{
  received,
  duplicate,
}

Also returns (200):

{
  received,
  recorded,
  order_id,
}

Error (401):

{
  error,
}

Error (401):

{
  error,
}

Error (500):

{
  error,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/webhooks/resend' \
  -H 'Content-Type: application/json'

POST Webhooks Shipstation :event#

Endpoint: POST /webhooks/shipstation/:event Authentication: Public (Optional)

URL Parameters#

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success (200):

{
  received,
  mode,
}

Also returns (200):

{
  received,
  mode,
  routed,
}

Also returns (200):

{
  received,
  mode,
}

Also returns (200):

{
  received,
  mode,
  routed,
}

Error (404):

{
  error,
}

Error (401):

{
  error,
}

Error (401):

{
  error,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/webhooks/shipstation/:event' \
  -H 'Content-Type: application/json'

POST Webhooks Stripe-tolerant#

Endpoint: POST /webhooks/stripe-tolerant Authentication: Public (Optional)

Description#

Custom Stripe webhook handler with extended tolerance This endpoint replaces the default /webhooks/payment/pp_stripe_stripe to handle webhook events with a 10-minute tolerance window instead of 5 minutes. Use this URL in Stripe Dashboard: https://your-domain.com/webhooks/stripe-tolerant

Request Body#

This route does not declare a validation schema, so the accepted fields are not derivable from the source. Check the handler before relying on a particular body.

Response#

Success (200):

{
  received,
  skipped,
  reason,
  eventId,
  action,
  sessionId,
}

Also returns (200):

{
  received,
  skipped,
  reason,
  eventId,
  action,
  sessionId,
}

Also returns (200):

{
  received,
  skipped,
  reason,
  eventId,
  action,
  sessionId,
}

Also returns (200):

{
  received,
  eventId,
  action,
}

Also returns (200):

{
  received,
  error,
}

Error (500):

{
  error,
}

Error (500):

{
  error,
}

Error (400):

{
  error,
}

Error (400):

{
  error,
}

Example Request#

curl -X POST 'https://your-store.omnicart.cc/webhooks/stripe-tolerant' \
  -H 'Content-Type: application/json'