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-interactive

After 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-interactive

All 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).

FlagDefaultNotes
--name TEXTDerived from the type and the URL hostThe name shown in list and in the audit log
--url TEXTNoneRequired. Checked against the address check below when you add it, and again at delivery.
--secret-env TEXTNoneThe 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 TEXTNoneWebex room ID. Required for webex, ignored for other types.
--min-severity [critical|high|medium|low|info]HIGHEvents below this level are dropped. Any letter case is accepted.
--events TEXTAll categoriesComma-separated list from block, scan, guardrail, drift, health
--timeout-seconds INTEGER10Timeout for each delivery
--cooldown-seconds INTEGER300 (the runtime default when omitted)Deduplication window. 0 turns it off.
--enabled / --disabled--enabledInitial state
--connector TEXTGlobalScope 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-runOffPrint the YAML changes without writing them
--non-interactiveOffUse 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:

TypeSuggested variable
slackNone. The secret is in the URL.
pagerdutyDEFENSECLAW_PD_ROUTING_KEY
webexDEFENSECLAW_WEBEX_TOKEN
genericDEFENSECLAW_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:// or https://, 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:

VariableAllows
DEFENSECLAW_WEBHOOK_ALLOW_LOCALHOST=1localhost and loopback addresses
DEFENSECLAW_ALLOW_CGNAT=1The 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 OK

Send a real test event. Each call uses a new event ID, so receivers do not deduplicate it.

defenseclaw setup webhook test slack-alerts

Check 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 --yes

Common gotchas

  • does not look like an environment variable name. --secret-env takes a name made of capital letters, digits and underscores. Store the value with defenseclaw keys set.
  • private or reserved address. The URL fails the address check. For a receiver on your own machine during development, set DEFENSECLAW_WEBHOOK_ALLOW_LOCALHOST=1 where the gateway starts. It allows loopback only.
  • PagerDuty key is unset. Set the environment variable named by secret_env before testing, including with --dry-run; the routing key is needed to format the payload.

See also