Webhooks
The catch-all trigger — let anything that can POST JSON hand CUGA an event to act on.
When there's no built-in integration, the generic webhook is the universal inbound trigger: any system that can POST JSON — a monitor, a SaaS's custom webhook, a CI job, a cron on another box — can hand CUGA an event.
EVENTS_WEBHOOK_KEY=… # generate: python3 -c "import secrets; print(secrets.token_urlsafe(32))"The endpoint
POST https://<your-events-url>/api/events/hook/<name>?key=<EVENTS_WEBHOOK_KEY>
Content-Type: application/json
{ "any": "json you like" }<name>is a label you choose (e.g.alerts,ci) — it's how a watcher targets this hook.- The
keymust matchEVENTS_WEBHOOK_KEY. Without it (or if the key is unset) the endpoint 401s every request — it fails closed. - The body is delivered to the armed watcher as the event payload.
Fast ack, async work
The endpoint returns 202 Accepted immediately and runs the agent in the background — so a caller
that expects a quick webhook ack won't time out. Add ?wait=1 to run synchronously and get the result
in the response instead.
Arm and fire
/automate when my "alerts" webhook fires, triage the payload and post the severityReply yes, then send a test event:
curl -sS -X POST \
"https://<your-events-url>/api/events/hook/alerts?key=$EVENTS_WEBHOOK_KEY" \
-H "Content-Type: application/json" \
-d '{"service":"checkout","status":"degraded"}'
# → 202 {"ok":true,"accepted":true,...}The watcher matches the alerts hook, runs the agent on your payload, and delivers the verdict to the
target you armed.
Want to watch a service that has no webhooks — an endpoint, a page, an API? Use a poll instead: "check this URL every 10 minutes and tell me only if it changed." See Triggers.
