# Custom HTTPS connector

Use these small senders when an application can produce the SiteWatch report JSON but does not need the bundled Node, Python, PHP or WordPress connector. They only send the report; your application remains responsible for collecting truthful checks and inventory.

- Windows: PowerShell 5.1 or 7 and .NET HttpClient.
- Linux/macOS: POSIX shell and curl.

Create a connector-enabled website in SiteWatch. Store its one-time token in the monitored host's secret manager and provide `SITEWATCH_URL`, `SITEWATCH_SITE_ID` and `SITEWATCH_TOKEN` as environment variables. Keep the token server-side, per website. Do not put it in browser/mobile code, source control, script arguments, or routine logs.

Download `report.example.json` as a starting point. Replace every placeholder with evidence collected by your app. Its sample check deliberately reports `warning` so it cannot make a new integration look healthy. See the [report v1 contract](../../docs/CONNECTORS.md#custom-connector-http-contract-report-v1), then send your UTF-8 JSON file:

For editor validation and code-generation tools, use the [versioned JSON Schema](report-v1.schema.json). The server remains authoritative: it rejects invalid required checks and discards unknown inventory/metric fields. The schema does not grant access to private platform state; your application still decides what it can observe.

```powershell
$env:SITEWATCH_URL = 'https://monitor.example.com'
$env:SITEWATCH_SITE_ID = '<website-id>'
$env:SITEWATCH_TOKEN = '<read-from-your-secret-manager>'
.\connectors\custom-http\send-report.ps1 -ReportPath 'C:\private\sitewatch-report.json'
```

```sh
export SITEWATCH_URL='https://monitor.example.com'
export SITEWATCH_SITE_ID='<website-id>'
export SITEWATCH_TOKEN="$(secret-manager-read sitewatch/token)"
./connectors/custom-http/send-report.sh /private/sitewatch-report.json
```

The shell sender keeps the bearer header in a mode-restricted temporary curl config and removes it on exit; it does not place the token in curl's command-line arguments. PowerShell keeps the token in the process request header. Both scripts require HTTPS, accept only the explicit `HTTP` loopback test override, cap JSON at 256 KiB, and disable redirect following. A successful HTTP 202 means SiteWatch recorded the report; it does not certify the host as clean. On HTTP 429, both scripts print the server's `Retry-After` value when present; wait that long before trying again. Do not retry unchanged 400/401 reports.

These examples validate transport on the CI host matrix. They do not install a service, scan files, infer health, or prove compatibility with every runtime; richer inventory requires a specialized collector.