Webhook Subscriptions

Create dynamic webhook subscriptions so external services (GitHub, GitLab, Stripe, CI/CD, IoT sensors, monitoring tools) can trigger the agent agent runs by POSTing events to a URL.

Setup (Required First)

The webhook platform must be enabled before subscriptions can be created. Check with:

the agent webhook list

If it says "Webhook platform is not enabled", set it up:

Option 1: Setup wizard

the agent gateway setup

Follow the prompts to enable webhooks, set the port, and set a global HMAC secret.

Option 2: Manual config

Add to ~/.mateclaw/config.yaml:

platforms:
  webhook:
    enabled: true
    extra:
      host: "0.0.0.0"
      port: 8644
      secret: "generate-a-strong-secret-here"

Option 3: Environment variables

Add to ~/.mateclaw/.env:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644
WEBHOOK_SECRET=generate-a-strong-secret-here

After configuration, start (or restart) the gateway:

the agent gateway run
# Or if using systemd:
systemctl --user restart the agent-gateway

Verify it's running:

curl http://localhost:8644/health

Commands

All management is via the the agent webhook CLI command:

Create a subscription

the agent webhook subscribe <name> \
  --prompt "Prompt template with {payload.fields}" \
  --events "event1,event2" \
  --description "What this does" \
  --skills "skill1,skill2" \
  --deliver telegram \
  --deliver-chat-id "12345" \
  --secret "optional-custom-secret"

Returns the webhook URL and HMAC secret. The user configures their service to POST to that URL.

List subscriptions

the agent webhook list

Remove a subscription

the agent webhook remove <name>

Test a subscription

the agent webhook test <name>
the agent webhook test <name> --payload '{"key": "value"}'

Prompt Templates

Prompts support {dot.notation} for accessing nested payload fields: