Webhook alerts
Configure Slack, PagerDuty, Webex, and generic HMAC webhooks so the gateway can ping a chat or incident channel when high-severity events fire.
Shell examples
The shell examples require Bash. On native Windows, use Git Bash or WSL; PowerShell uses different continuation and environment-variable syntax.
Notifiers and telemetry destinations
A webhook notifier posts a chat or incident message when an event meets your minimum severity. Notifiers are separate from telemetry destinations: they filter by severity, deduplicate, and format the message for the receiver.
To export every event as JSON Lines to a SIEM instead, add an http_jsonl destination with defenseclaw setup observability add webhook.
The four webhook types
The webhook type is slack, pagerduty, webex or generic (a payload signed with HMAC-SHA256).
Before you start
- The receiver's URL. It must resolve to a public address. Private, loopback, link-local and cloud-metadata addresses are refused.
- For PagerDuty, Webex and signed generic webhooks: store the secret first with
defenseclaw keys set <NAME>. Pass the variable name to--secret-env, never the secret.
Worked examples
Pick your receiver.
The secret is in the URL, so there is no --secret-env.
defenseclaw setup webhook add slack \
--name slack-alerts \
--url https://hooks.slack.com/services/T000/B000/XXXXXX \
--min-severity HIGH \
--non-interactive Webhook 'slack-alerts' [slack]
YAML changes:
- webhooks: 0 -> 1 entries
- webhooks[slack-alerts] type=slack enabled=True severity=HIGH
Config updated. Gateway is not running - changes will take effect on next start.defenseclaw keys set DEFENSECLAW_PD_ROUTING_KEY
defenseclaw setup webhook add pagerduty \
--name pd-prod \
--url https://events.pagerduty.com/v2/enqueue \
--secret-env DEFENSECLAW_PD_ROUTING_KEY \
--min-severity HIGH \
--non-interactiveAfter you rotate the key, run defenseclaw-gateway restart. Webex works the same way with --secret-env for the bot token and --room-id.
The body is signed with HMAC-SHA256 in the X-Hub-Signature-256 header, as sha256=<hex>.
Generic test events include event.host, the CLI machine's hostname. Each test uses a new event ID. show and list redact URL paths and queries because they can carry credentials.
defenseclaw keys set DEFENSECLAW_SIEM_SECRET
defenseclaw setup webhook add generic \
--name siem \
--url https://siem.example.com/defenseclaw \
--secret-env DEFENSECLAW_SIEM_SECRET \
--events block,guardrail \
--min-severity MEDIUM \
--non-interactiveAll subcommands
defenseclaw setup webhook has the subcommands add, list, show, test, enable, disable and remove.
Flag reference for add
defenseclaw setup webhook add [OPTIONS] <type><type> is slack, pagerduty, webex or generic (a payload signed with HMAC-SHA256).
| Flag | Default | Notes |
|---|---|---|
--name TEXT | Derived from the type and the URL host | The name shown in list and in the audit log |
--url TEXT | None | Required. Checked against the address check below when you add it, and again at delivery. |
--secret-env TEXT | None | The name of an environment variable, never the secret. Required for pagerduty and webex. It must look like a variable name (capital letters, digits and underscores). |
--room-id TEXT | None | Webex room ID. Required for webex, ignored for other types. |
--min-severity [critical|high|medium|low|info] | HIGH | Events below this level are dropped. Any letter case is accepted. |
--events TEXT | All categories | Comma-separated list from block, scan, guardrail, drift, health |
--timeout-seconds INTEGER | 10 | Timeout for each delivery |
--cooldown-seconds INTEGER | 300 (the runtime default when omitted) | Deduplication window. 0 turns it off. |
--enabled / --disabled | --enabled | Initial state |
--connector TEXT | Global | Scope the webhook to one connector. That connector's events go to its own webhooks when it has any, and to the global webhooks otherwise. list and remove take the same option. |
--dry-run | Off | Print the YAML changes without writing them |
--non-interactive | Off | Use flags only. A missing required value exits non-zero with a message such as pagerduty: --secret-env is required (routing key / bot token). |
The interactive prompt suggests these variable names for --secret-env:
| Type | Suggested variable |
|---|---|
slack | None. The secret is in the URL. |
pagerduty | DEFENSECLAW_PD_ROUTING_KEY |
webex | DEFENSECLAW_WEBEX_TOKEN |
generic | DEFENSECLAW_WEBHOOK_SECRET, after it asks whether to sign with HMAC |
Store the value with defenseclaw keys set <NAME> before you test.
SSRF guard
Every URL goes through the same check at add time and again at delivery, so a hand edit to config.yaml is caught too:
- The scheme is
http://orhttps://, and the host parses. - The host resolves to a public address. Private (RFC 1918 and IPv6 unique-local), link-local, loopback, cloud-metadata and carrier-grade NAT (100.64.0.0/10) addresses are refused.
- The URL has no credentials (
https://user:pass@host). Put them in--secret-env. A Slack URL is the one place a secret in the URL is expected.
Two environment variables open one range each and nothing else:
| Variable | Allows |
|---|---|
DEFENSECLAW_WEBHOOK_ALLOW_LOCALHOST=1 | localhost and loopback addresses |
DEFENSECLAW_ALLOW_CGNAT=1 | The 100.64.0.0/10 range, used by Tailscale and similar overlays |
A private address stops at add:
IP 10.0.0.5 is a private or reserved address; webhooks must reach a public address so events can't be sent to internal services (SSRF guard). Use a public endpoint or relay.On a managed computer the gateway ignores these two variables (Environment variables).
Verifying a webhook with test
Check the payload without sending it.
defenseclaw setup webhook test slack-alerts --dry-run Testing webhook slack-alerts [slack] -> https://hooks.slack.com/***
(dry-run) formatting only, no delivery
Payload: 459 bytes
Preview: {"attachments":[{"color":"#FF6600","blocks":[{"type":"header", …
Headers:
Content-Type: application/json
User-Agent: defenseclaw-cli/webhook-test
OK Result: dry-run OKSend a real test event. Each call uses a new event ID, so receivers do not deduplicate it.
defenseclaw setup webhook test slack-alertsCheck it worked
defenseclaw setup webhook list Webhooks
--------
NAME TYPE ENABLED SEVERITY URL
-------------------------------- ---------- -------- ---------- ----------------------------------------
slack-alerts slack yes HIGH https://hooks.slack.com/***The message should appear in the channel. If the test returns HTTP 200 and nothing shows, check the channel allowlist on the Slack app.
Undo
defenseclaw setup webhook disable slack-alerts
defenseclaw setup webhook remove slack-alerts --yesCommon gotchas
does not look like an environment variable name.--secret-envtakes a name made of capital letters, digits and underscores. Store the value withdefenseclaw keys set.private or reserved address. The URL fails the address check. For a receiver on your own machine during development, setDEFENSECLAW_WEBHOOK_ALLOW_LOCALHOST=1where the gateway starts. It allows loopback only.- PagerDuty key is unset. Set the environment variable named by
secret_envbefore testing, including with--dry-run; the routing key is needed to format the payload.
See also
- Send to Splunk: export every event, with no severity floor.
- Alert runbooks
Splunk
defenseclaw setup splunk configures three independent pipelines — a local Splunk in Docker for demos, remote Splunk Enterprise through HEC, and Splunk Observability Cloud through OTLP.
Redaction
Configure centralized, field-aware redaction independently for local history, buckets, and export destinations in DefenseClaw observability.