# `POST /api/v1/daemonx/onboarding/sessions/:id/webhook/replay`

> **Endpoint:** `POST /api/v1/daemonx/onboarding/sessions/:id/webhook/replay`  
> **Auth Scope:** Developer Token Protected (Writable Token Required)  
> **Target Service:** Nyxzie Cloud Core API  
> **Introduced In:** v1.0.0  
> **Last Updated:** v1.0.0  

---

## 1. Description & Purpose

`POST /api/v1/daemonx/onboarding/sessions/:id/webhook/replay` queues a redelivery of the `daemonx.onboarding.completed` webhook event for an already completed onboarding session.

Use cases:
1. **Developer Downtime Recovery:** If the developer's receiving webhook service was down, returned a 5xx error, or suffered a network timeout when the workstation originally completed pairing.
2. **Ops Resync:** Enables administrative tooling and background reconciliation workers to trigger a fresh webhook dispatch without requiring counter re-pairing or database intervention.
3. **Outbox Guarantee:** Generates a new pending outbox entry with a fresh `event_id` in `daemonx_webhook_events` that is immediately picked up by the outbox dispatcher.

> [!NOTE]
> This endpoint only accepts sessions that have successfully reached `"completed"` status. It cannot replay pending, expired, or cancelled sessions.

---

## 2. Request Headers

| Header Name | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `Authorization` | `string` | **Yes** | Developer API Bearer Token (must have write permissions) | `Bearer nyx_daemonx_live_6b431eda073e...` |
| `Accept` | `string` | No | Response format | `application/json` |

---

## 3. Path Parameters

| Parameter | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `id` | `string` (UUID) | **Yes** | Completed onboarding session UUID. | `4b68ff5e-f001-4475-8025-a741544256eb` |

---

## 4. Request Body

No request body is needed for this endpoint.

---

## 5. Successful Response Example (201 Created)

When the event is successfully queued in the outbox:

```json
{
  "success": true,
  "webhook": {
    "event_id": "dxe_9c2409f87c9343df8995a557",
    "event_type": "daemonx.onboarding.completed",
    "status": "pending"
  }
}
```

> [!TIP]
> The API returns the newly allocated outbox handle (`event_id` with `status: "pending"`). The actual webhook dispatch occurs asynchronously through the outbox dispatcher to the developer's configured webhook endpoint.

---

## 6. Dispatched Webhook Payload Structure

When the outbox dispatcher delivers the replayed webhook to your registered HTTPS endpoint, the HTTP `POST` body contains:

```json
{
  "event": "daemonx.onboarding.completed",
  "event_id": "dxe_9c2409f87c9343df8995a557",
  "onboarding_session_id": "4b68ff5e-f001-4475-8025-a741544256eb",
  "environment": "live",
  "is_sandbox": false,
  "external_customer_ref": "cust_milan_01",
  "external_location_ref": "loc_colombo_flagship",
  "external_counter_ref": "pos_lane_01",
  "counter_id": "d402ddec-ecf7-4b39-b57a-86ce6008df05",
  "counter_name": "Cashier Counter 1",
  "occurred_at": "2026-10-07T02:35:10.000Z"
}
```

Webhooks include the standard Nyxzie signature header:
- `X-DaemonX-Signature`: HMAC SHA-256 signature calculated over the raw request body using your developer webhook signing secret.

---

## 7. Error Responses

### 7.1. Session Not Completed (`404 Not Found`)
Returned if the session UUID does not exist under your developer profile, or if the session is not in `"completed"` status (e.g. still pending, expired, or cancelled):
```json
{
  "success": false,
  "error": "Completed DaemonX onboarding session not found.",
  "code": "DAEMONX_ONBOARDING_SESSION_NOT_COMPLETED"
}
```

### 7.2. Read-Only Token Used (`403 Forbidden`)
If a read-only developer token attempts to replay a webhook:
```json
{
  "success": false,
  "error": "DaemonX token does not have write permissions.",
  "code": "DAEMONX_TOKEN_READ_ONLY"
}
```

---

## 8. TypeScript Contracts

```typescript
export interface DaemonxOnboardingWebhookReplayResponse {
  success: true;
  webhook: {
    event_id: string;
    event_type: 'daemonx.onboarding.completed';
    status: 'pending' | string;
  };
}

export interface DaemonxOnboardingCompletedWebhookPayload {
  event: 'daemonx.onboarding.completed';
  event_id: string;
  onboarding_session_id: string;
  environment: 'live' | 'sandbox';
  is_sandbox: boolean;
  external_customer_ref: string | null;
  external_location_ref: string | null;
  external_counter_ref: string | null;
  counter_id: string;
  counter_name: string;
  occurred_at: string;
}
```

---

## 9. cURL Example

```bash
curl -X POST https://api.nyxzie.com/api/v1/daemonx/onboarding/sessions/4b68ff5e-f001-4475-8025-a741544256eb/webhook/replay \
  -H "Authorization: Bearer nyx_daemonx_live_6b431eda073e6cb462bd0a9971687376ef5481887c46dfa688bcb618982fc905"
```