webhook-subscriptions

Files (1)

• SKILL.md

SKILL.md (first lines)

## Kheish Compatibility

This skill is repo-local and stays inactive until explicitly activated.

When the original instructions refer to legacy tool names, use these Kheish mappings:

- `terminal` => `bash`
- `web_extract` => `web_fetch`, plus `web_search` when discovery is needed
- `search_files` => `grep_search` and `glob_search`
- `browser_*` tools require a browser-capable surfaced tool or MCP; if none is available, use the closest available surface and say so explicitly

When the instructions mention local helper files, resolve them from `${KHEISH_SKILL_DIR}`.

Kheish does not currently ship a dedicated webhook subscription CLI. In the examples below,
`webhook-manager` and `gateway-manager` are placeholders for your deployment tooling around
daemon connector config, ingress routing, and lifecycle management.

# Webhook Subscriptions

Create dynamic webhook subscriptions so external services (GitHub, GitLab, Stripe, CI/CD, IoT sensors, monitoring tools) can trigger Kheish 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
webhook-manager list
```

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

### Option 1: Setup wizard
```bash
gateway-manager setup
```
Follow the prompts to enable webhooks, set the port, and set a global HMAC secret.

### Option 2: Manual config
Add to `~/.kheish/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 `~/.kheish/.env`:
```bash
WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644
WEBHOOK_SECRET=generate-a-strong-secret-here
```

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

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

## Commands

All management is via the `webhook-manager` CLI command:

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

### Remove a subscription
```bash
webhook-manager remove <name>
```

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

## Prompt Templates

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

- `{issue.title}` — GitHub issue title
- `{pull_request.user.login}` — PR author
- `{data.object.amount}` — Stripe payment amount
- `{sensor.temperature}` — IoT sensor reading

If no prompt is specified, the full JSON payload is dumped into the agent prompt.

## Common Patterns

### GitHub: new issues
```bash
webhook-manager subscribe github-issues \
  --events "issues" \

From graniet/kheish, Apache-2.0.

More from graniet/kheish