Webhook config

The firewall can POST decisions to any HTTPS endpoint: a Sentinel or Defender XDR ingestion function, a log collector, or an automation tool that opens tickets on blocks. Configuration is environment variables on the container.

By default each POST carries one JSON event (Content-Type: application/json). With WEBHOOK_BATCH_ENABLED=true, events are batched as NDJSON (application/x-ndjson, one event per line). A receiver that splits the body on newlines handles both.

📘

Using Splunk?

Skip the webhook and use the native exporter: Splunk config.

1. Add the variables

Append to the firewall's .env:

WEBHOOK_ENABLED=true
WEBHOOK_URL=https://collector.example.com/socket-firewall
WEBHOOK_AUTH_HEADER=Bearer your_receiver_token   # optional, sent as Authorization
WEBHOOK_ON_BLOCK=true
WEBHOOK_ON_WARN=true
WEBHOOK_ON_IGNORE=true
WEBHOOK_ON_MONITOR=true
WEBHOOK_SSL_VERIFY=true

Leave the WEBHOOK_BATCH_* settings at their defaults (batching off) unless your receiver needs fewer requests. If you turn batching on, note that WEBHOOK_BATCH_SIZE is measured in bytes, not events.

🚧

Turn on all four WEBHOOK_ON_* flags

The most common mistake is setting only WEBHOOK_ON_BLOCK. Your SIEM then sees blocks and nothing else, so it can't show what was allowed or who is installing what. Set the flags to false only for events you deliberately don't want.

2. Recreate the container

Environment variables are read at startup. A plain restart doesn't pick up .env changes.

docker compose up -d --force-recreate

3. Generate events

From a client pointed at the firewall:

Use a fresh directory: if lodash is already in node_modules, npm downloads nothing and no event is sent.

cd "$(mktemp -d)"
npm cache clean --force
npm install lodash     # clean allow
npm install lodahs     # blocked

Verify

Check your receiver, and compare with the firewall's own log:

docker compose logs socket-firewall | grep SOCKET_DECISION

• The blocked install arrives with purl, block_reason, and request_id
• The allowed install also arrives (proves you're not getting blocks only)
• Event counts at the receiver match the SOCKET_DECISION lines (requires SOCKET_IGNORE_LOG_LEVEL=warn, see Data)

No receiver yet? Test locally

A throwaway listener that prints each POST. Run it on a machine the container can reach:

python3 - <<'PY'
from http.server import BaseHTTPRequestHandler, HTTPServer
class H(BaseHTTPRequestHandler):
    def do_POST(self):
        n = int(self.headers.get("Content-Length", 0))
        print(self.rfile.read(n).decode(), flush=True)   # one event, or NDJSON if batching is on
        self.send_response(200); self.end_headers()
HTTPServer(("0.0.0.0", 9000), H).serve_forever()
PY

Set WEBHOOK_URL=http://LISTENER_IP:9000/ and WEBHOOK_SSL_VERIFY=false, recreate the container, and install a package. Switch back to your real endpoint after.

Routing to a SIEM

Reference

• Data for the event fields