# Webhooks

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

## Overview

This section documents 5 API routes for webhooks.

## Quick Reference

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/webhooks/cartrover` | CartRover (Extensiv Integration Manager) Webhook Handler — `... |
| POST | `/webhooks/quickbox` | No description |
| POST | `/webhooks/resend` | No description |
| POST | `/webhooks/shipstation/:event` | No description |
| POST | `/webhooks/stripe-tolerant` | Custom Stripe webhook handler with extended tolerance This e... |

---

## 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):**
```typescript
{
  received,
  mode,
}
```
**Also returns (200):**
```typescript
{
  received,
  mode,
  routed,
}
```
**Also returns (200):**
```typescript
{
  received,
  mode,
}
```
**Also returns (200):**
```typescript
{
  received,
  mode,
  routed,
}
```

### Example Request

```bash
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):**
```typescript
{
  received,
  mode,
  signature_checked,
  signature_valid,
}
```
**Also returns (200):**
```typescript
{
  received,
  mode,
}
```

**Error (401):**
```typescript
{
  error,
}
```
**Error (500):**
```typescript
{
  error,
}
```

### Example Request

```bash
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):**
```typescript
{
  received,
  mode,
}
```
**Also returns (200):**
```typescript
{
  received,
  handled,
}
```
**Also returns (200):**
```typescript
{
  received,
  correlated,
}
```
**Also returns (200):**
```typescript
{
  received,
  duplicate,
}
```
**Also returns (200):**
```typescript
{
  received,
  duplicate,
}
```
**Also returns (200):**
```typescript
{
  received,
  recorded,
  order_id,
}
```

**Error (401):**
```typescript
{
  error,
}
```
**Error (401):**
```typescript
{
  error,
}
```
**Error (500):**
```typescript
{
  error,
}
```

### Example Request

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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `event` | string | Yes | Event identifier |

### 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):**
```typescript
{
  received,
  mode,
}
```
**Also returns (200):**
```typescript
{
  received,
  mode,
  routed,
}
```
**Also returns (200):**
```typescript
{
  received,
  mode,
}
```
**Also returns (200):**
```typescript
{
  received,
  mode,
  routed,
}
```

**Error (404):**
```typescript
{
  error,
}
```
**Error (401):**
```typescript
{
  error,
}
```
**Error (401):**
```typescript
{
  error,
}
```

### Example Request

```bash
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):**
```typescript
{
  received,
  skipped,
  reason,
  eventId,
  action,
  sessionId,
}
```
**Also returns (200):**
```typescript
{
  received,
  skipped,
  reason,
  eventId,
  action,
  sessionId,
}
```
**Also returns (200):**
```typescript
{
  received,
  skipped,
  reason,
  eventId,
  action,
  sessionId,
}
```
**Also returns (200):**
```typescript
{
  received,
  eventId,
  action,
}
```
**Also returns (200):**
```typescript
{
  received,
  error,
}
```

**Error (500):**
```typescript
{
  error,
}
```
**Error (500):**
```typescript
{
  error,
}
```
**Error (400):**
```typescript
{
  error,
}
```
**Error (400):**
```typescript
{
  error,
}
```

### Example Request

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

---