Webhooks

Webhooks let external services trigger Mona. This is the foundation for automation — GitHub PRs, CI/CD pipelines, monitoring alerts, and more.

How webhooks work

An external service sends an HTTP POST to your webhook URL
MonoClaw receives the payload
Mona processes the event according to your subscription rules
Results are delivered to your configured channels

Creating a webhook subscription

monoclaw webhook subscribe pr-review \
  --events "pull_request" \
  --prompt "Review PR #{pull_request.number}: {pull_request.title}. Check for security issues, code quality, and test coverage." \
  --skills "github-code-review" \
  --deliver github_comment

GitHub webhooks

1. Configure the webhook in GitHub

Go to your repository → Settings → Webhooks
Click Add webhook
Payload URL: https://your-domain.com/webhooks/github
Content type: application/json
Select events:
- Pull requests
- Issues
- Pushes
- Releases
Add webhook

2. Create a subscription in MonoClaw

monoclaw webhook subscribe auth-watch \
  --events "pull_request" \
  --prompt "PR #{pull_request.number}: {pull_request.title} by {pull_request.user.login}. Check if it touches the auth-provider module. If yes, summarize the changes." \
  --deliver slack

GitLab webhooks

Similar to GitHub:

Go to Settings → Webhooks in GitLab
URL: https://your-domain.com/webhooks/gitlab
Select events (Merge requests, Issues, Push events)
Create webhook

monoclaw webhook subscribe gitlab-mr \
  --events "merge_request" \
  --prompt "Review MR #{object_attributes.iid}: {object_attributes.title}" \
  --deliver telegram

Custom webhooks

Any service that can POST JSON can trigger Mona:

monoclaw webhook subscribe alert-triage \
  --prompt "Alert: {alert.name} — Severity: {alert.severity}. Find the owning service, investigate, and post a triage summary with proposed first steps." \
  --deliver slack

Send a test payload:

curl -X POST https://your-domain.com/webhooks/custom/alert-triage \
  -H "Content-Type: application/json" \
  -d '{"alert": {"name": "CPU High", "severity": "critical"}}'

Webhook security

HMAC verification

MonoClaw verifies webhook signatures using HMAC:

# ~/.monoclaw/config.yaml
webhooks:
  github:
    secret: "${GITHUB_WEBHOOK_SECRET}"
  gitlab:
    secret: "${GITLAB_WEBHOOK_SECRET}"

IP allowlisting

Restrict webhook sources:

webhooks:
  allowed_ips:
    - "140.82.112.0/20"    # GitHub
    - "34.74.0.0/16"       # GitLab

Managing subscriptions

monoclaw webhook list
monoclaw webhook delete pr-review
monoclaw webhook pause auth-watch
monoclaw webhook resume auth-watch

Best practices

Use secrets — Always verify webhook signatures
Filter events — Only subscribe to events you need
Use [SILENT] — For monitoring webhooks, suppress no-op results
Test payloads — Use curl to test before going live
Handle retries — Webhook sources may retry on failure

Troubleshooting

Problem	Fix
"Webhook signature invalid"	Check secret matches between sender and MonoClaw
"Event not handled"	Verify the event type is in your subscription
"Payload too large"	Increase `webhooks.max_payload_size`
Delivery timeouts	Check network and MonoClaw gateway status