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.