Webhook payload reference

This page follows the current master implementation. All webhook requests are JSON objects sent to the active webhook URL. Receivers must ignore unknown fields so newer Smithproxy builds can extend payloads safely.

Common envelope

Connection actions use:

{
  "action": "connection-start",
  "id": "Proxy-BOOTID-PTR-OBJECT",
  "source": "edge-01",
  "type": "proxy",
  "details": {}
}
Field Meaning
action event/action name
id process-local connection identifier
source configured webhook hostid, otherwise host name
type currently proxy
details action-specific object

The connection id is for correlation during one process lifetime. Do not treat it as a stable identifier across restarts.

Ping

{
  "action": "ping",
  "source": "edge-01",
  "type": "proxy",
  "instance": "instance-id",
  "proxies": ["Proxy-...", "Proxy-..."]
}

An extended ping can also contain proxies-plus, with richer session information. A 202 response to a normal action triggers an extended ping and neighbor update, so receivers should return 202 only when they want that refresh.

Connection start

{
  "action": "connection-start",
  "id": "Proxy-...",
  "source": "edge-01",
  "type": "proxy",
  "details": {
    "info": {
      "session": "ssl_192.0.2.10:53000+ssl_198.51.100.20:443"
    }
  }
}

Connection stop

{
  "action": "connection-stop",
  "id": "Proxy-...",
  "source": "edge-01",
  "type": "proxy",
  "details": {
    "info": {
      "session": "ssl_192.0.2.10:53000+ssl_198.51.100.20:443",
      "policy": 3,
      "bytes_up": 1420,
      "bytes_down": 8392,
      "ja4_ch": "...",
      "ja4_ch_ignore_sni": false,
      "ja4_sh": "...",
      "tls": {"sni": "example.com"},
      "l7": {
        "app": "HTTP",
        "details": [],
        "signatures": []
      }
    }
  }
}

tls and l7 are omitted when unavailable. L7 fields depend on the active application engine and may include an engine-specific list.

Access request

A policy with the access-request feature sends:

{
  "action": "access-request",
  "id": "Proxy-...",
  "source": "edge-01",
  "type": "proxy",
  "details": {
    "session": "...",
    "policy": 3,
    "require": "origin-info",
    "bytes_side": "L",
    "bytes_size": 0,
    "state": "INIT"
  }
}

Return a 2xx response with one of:

{"access-response":"accept"}
{"access-response":"reject"}

The current implementation logs a fail-open condition when it receives no usable 2xx JSON response. Design the receiver and surrounding network policy with that behavior in mind.

Content request and replacement

When a content profile enables webhooks, Smithproxy sends chunks as base64:

{
  "action": "connection-content",
  "id": "Proxy-...",
  "source": "edge-01",
  "type": "proxy",
  "details": {
    "info": {
      "session": "...",
      "side": "L",
      "content": "YmFzZTY0LWRhdGE="
    }
  }
}

For a 2xx response:

  • {"action":"discard"} removes the submitted chunk;
  • {"action":"replace","content":"...base64..."} replaces it;
  • a JSON object without action leaves the chunk unchanged.

Invalid JSON, non-2xx responses and missing responses do not produce a replacement. Synchronous content processing can block traffic; enforce short receiver timeouts and payload limits.

Neighbor events

{
  "action": "neighbor",
  "state": "new",
  "source": "edge-01",
  "type": "proxy",
  "addresses": ["192.0.2.10"]
}

States include runtime update operations such as new, update and ping. Neighbor responses can update stored neighbor data/tags and therefore must be authenticated and validated by the receiver.

Receiver checklist

  • require HTTPS and authenticate Smithproxy independently of source IP;
  • accept only known source values and bound payload sizes;
  • respond idempotently to repeated lifecycle events;
  • do not assume event ordering across concurrent connections;
  • redact credentials and base64 content from normal logs;
  • return 202 intentionally, because it requests additional state refresh;
  • monitor latency, error rate and receiver saturation.