Create and manage webhook subscriptions for event-driven agent activation, or for direct push notifications (zero LLM cost). Use when the user wants external services to trigger agent runs OR push notifications to chats.
Create and manage webhook subscriptions for event-driven agent activation, or for direct push notifications (zero LLM cost). Use when the user wants external services to trigger agent runs OR push notifications to chats.
version
1.1.0
metadata
{"community":{"tags":["webhook","events","automation","integrations","notifications","push"]},"upstream_import":{"original_name":"webhook-subscriptions","source":"community catalog active profile ~/.argent/skills"}}
Webhook Subscriptions
Create dynamic webhook subscriptions so external services (GitHub, GitLab, Stripe, CI/CD, IoT sensors, monitoring tools) can trigger community skills runs by POSTing events to a URL.
Setup (Required First)
The webhook platform must be enabled before subscriptions can be created. Check with:
community webhook list
If it says "Webhook platform is not enabled", set it up:
Option 1: Setup wizard
community gateway setup
Follow the prompts to enable webhooks, set the port, and set a global HMAC secret.
community webhook subscribe alerts \
--prompt "Alert: {alert.name}\nSeverity: {alert.severity}\nMessage: {alert.message}\n\nPlease investigate and suggest remediation." \
--deliver origin
Direct delivery (no agent, zero LLM cost)
For use cases where you just want to push a notification through to a user's chat — no reasoning, no agent loop — add --deliver-only. The rendered --prompt template becomes the literal message body and is dispatched directly to the target adapter.
Use this for:
External service push notifications (Supabase/Firebase webhooks → Telegram)
Monitoring alerts that should forward verbatim
Inter-agent pings where one agent is telling another agent's user something
Any webhook where an LLM round trip would be wasted effort
community webhook subscribe antenna-matches \
--deliver telegram \
--deliver-chat-id "123456789" \
--deliver-only \
--prompt "🎉 New match: {match.user_name} matched with you!" \
--description "Antenna match notifications"
The POST returns 200 OK on successful delivery, 502 on target failure — so upstream services can retry intelligently. HMAC auth, rate limits, and idempotency still apply.
Requires --deliver to be a real target (telegram, discord, slack, github_comment, etc.) — --deliver log is rejected because log-only direct delivery is pointless.
Security
Each subscription gets an auto-generated HMAC-SHA256 secret (or provide your own with --secret)
The webhook adapter validates signatures on every incoming POST
Static routes from config.yaml cannot be overwritten by dynamic subscriptions
Subscriptions persist to ~/.argent/webhook_subscriptions.json
How It Works
community webhook subscribe writes to ~/.argent/webhook_subscriptions.json
The webhook adapter hot-reloads this file on each incoming request (mtime-gated, negligible overhead)
When a POST arrives matching a route, the adapter formats the prompt and triggers an agent run
The agent's response is delivered to the configured target (Telegram, Discord, GitHub comment, etc.)
Troubleshooting
If webhooks aren't working:
Is the gateway running? Check with systemctl --user status community-gateway or ps aux | grep gateway
Is the webhook server listening?curl http://localhost:8644/health should return {"status": "ok"}
Signature mismatch? Verify the secret in your service matches the one from community webhook list. GitHub sends X-Hub-Signature-256, GitLab sends X-Gitlab-Token.
Firewall/NAT? The webhook URL must be reachable from the service. For local development, use a tunnel (ngrok, cloudflared).
Wrong event type? Check --events filter matches what the service sends. Use community webhook test <name> to verify the route works.
