---
name: integration-validation
description: "Manages Excel imports validation, zero-trust internal routing, and n8n webhook setups. Use this when importing sales, routing webhooks, configuring API endpoints, or troubleshooting 502/network issues."
---

# Integration Validation

Governs the validation of external file imports (e.g., Excel/CSV sales sheets) and the secure routing of n8n integration webhooks.

## Core Rationale
Ensuring data integrity at the system entry point prevents downstream calculation failures. Proper zero-trust routing isolates staging/test runs from production environments.

## Execution Rules

### 1. Webhook Isolation and Sandbox Branching
- **Branching Rule**: For all test runs and staging simulations, route webhook payloads strictly through the `/webhook-test` path instead of `/webhook`.
- **Target DB**: The `/webhook-test` endpoint must write only to the test database sandbox.
- **Why**: Prevents test data from contaminating real collaborator settlements and polluting production audit histories.

### 2. Zero-Trust Routing and Internal Hostnames
- **Container Name Routing**: Do not route requests via public IP or expose host ports unnecessarily. Connect via internal Docker hostnames behind the Caddy reverse proxy (e.g. `http://n8n:5678` or local reverse-proxied aliases).
- **Network Check**: If a `502 Bad Gateway` error occurs, verify that Caddy and the target service container share the same Docker network.

### 3. Idempotency & Double-Upload Prevention
- **Idempotency Key**: Every file upload or API payload must contain or generate a unique transaction/idempotency key.
- **Verification**: Query the database for the key before running the processing pipeline. If the key already exists, fail gracefully with a duplicate warning (e.g. "Duplicate import detected").

### 4. Layout Validation
- Ensure imported files have the correct column layout (Collaborator email/ID, Hotel, Amount, Date).
- Report validation errors formatted clearly so they can be rendered in the UI according to the user's active locale (en/es).