HTTP API and webhooks

Smithproxy provides two different integration surfaces:

  • the HTTP API queries diagnostics and changes supported configuration values;
  • webhooks send connection events to an external decision or collection service.

HTTP API

The API listens on HTTPS when enabled. The default implementation port is 55555, but the effective binding and port come from the active configuration.

Inspect runtime API information from the CLI:

diag api info

API authentication supports login requests and configured API-key headers. Do not publish the API on an untrusted interface. Use TLS verification, firewall restrictions and separate credentials for automation.

Authentication flow

POST /api/authorize accepts JSON containing an access_key. GET /api/authorize?key=... is also registered, but putting secrets in query strings risks leaking them to logs and browser history; prefer POST. A successful authorization creates an authentication token and CSRF token and returns corresponding cookies.

POST /api/login accepts form fields username and password when the build has PAM support. The account must belong to the configured administrator group. API-key authorization is better suited to non-interactive automation.

Registered endpoints

Method Path Protection Purpose
GET, POST /api/status/ping token in release builds version, status and uptime
GET /cacert public active public CA certificate
GET, POST /api/diag/ssl/cache/stats token certificate-cache statistics
GET, POST /api/diag/ssl/cache/print token certificate-cache content
GET, POST /api/diag/proxy/session/list token session diagnostics
GET, POST /api/diag/proxy/neighbor/list token neighbor database
POST /api/diag/proxy/neighbor/update token update neighbor information
GET, POST /api/do/ssl/custom/reload token reload custom certificates
POST /api/config/uni/get token read a supported configuration value
POST /api/config/uni/set token set a supported configuration value
POST /api/config/uni/add token add a supported configuration entry
POST /api/webhook/register token temporary webhook override
POST /api/webhook/unregister token clear temporary webhook override

Endpoint presence and accepted JSON fields remain build-specific. Inspect diag api info and test against a non-production instance before writing automation.

Authorization example

curl --fail --silent --show-error \
  --cacert /path/to/management-ca.pem \
  -H 'Content-Type: application/json' \
  -d '{"access_key":"REDACTED"}' \
  -c smithproxy.cookies \
  https://127.0.0.1:55555/api/authorize

Keep the cookie jar and returned CSRF token private. The exact header/cookie combination expected by protected mutations should be confirmed against the running release.

Webhook configuration

The webhook client can send HTTPS requests for connection lifecycle and policy actions. A minimal configuration has this shape:

settings = {
    webhook = {
        enabled = TRUE;
        url = "https://collector.example/smithproxy";
        tls_verify = TRUE;
        hostid = "edge-01";
    };
};

Exact schema fields may differ by release; use CLI completion and the shipped configuration schema as the authority.

Events include connection start/stop data, connection details and optional JA4/JA4S metadata. Policy features can also request an external access decision or send statistics. Content profiles may submit application content for synchronous replacement; this blocks the affected traffic while waiting and must be used with strict timeouts.

Dynamic registration

When allow_api_override is enabled, authenticated API calls can temporarily register or unregister a webhook target. Overrides expire and do not replace the persistent configuration.

Receiver requirements

  • respond quickly and enforce request-size limits;
  • authenticate the sender at the receiver;
  • keep TLS verification enabled;
  • treat connection metadata and captured content as sensitive;
  • make policy decisions deterministic when the receiver is degraded;
  • log webhook failures without recording secrets or full payloads unnecessarily.