# Webhook Subscriptions

Webhook subscriptions: event-driven agent runs.

- Repository: https://github.com/mateaix/mateclaw (1176 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mateaix/mateclaw --skill webhook-subscriptions -g -a claude-code -y`
Codex: `npx skills add mateaix/mateclaw --skill webhook-subscriptions -g -a codex -y`
Cursor: `npx skills add mateaix/mateclaw --skill webhook-subscriptions -g -a cursor -y`
Gemini CLI: `npx skills add mateaix/mateclaw --skill webhook-subscriptions -g -a gemini-cli -y`

## Description

Webhook subscriptions: event-driven agent runs.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:
```bash
the agent webhook list
```

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

### Option 1: Setup wizard
```bash
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`:
```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`:
```bash
WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644
WEBHOOK_SECRET=generate-a-strong-secret-here
```

After configuration, start (or restart) the gateway:
```bash
the agent gateway run
# Or if using systemd:
systemctl --user restart the agent-gateway
```

Verify it's running:
```bash
curl http://localhost:8644/health
```

## Commands

All management is via the `the agent webhook` CLI command:

### Create a subscription
```bash
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
```bash
the agent webhook list
```

### Remove a subscription
```bash
the agent webhook remove <name>
```

### Test a subscription
```bash
the agent webhook test <name>
the agent webhook test <name> --payload '{"key": "value"}'
```

## Prompt Templates

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

The rest: https://github.com/mateaix/mateclaw/blob/HEAD/mateclaw-server/src/main/resources/skills/webhook-subscriptions/SKILL.md