Events & webhooks tools

These tools cover Alpacon’s event system: browsing and searching the event log that records server activity, and configuring how events reach you outside the AI client through event subscriptions and webhook endpoints. Requests like “what happened on web-01 in the last day”, “notify our Slack webhook when a server config changes”, or “stop sending sudo alerts to that channel” all map to tools on this page.

Note

All tools accept workspace (required) and region (optional, defaults to the configured region). These common parameters are omitted from the tables below.

Summary

Tool	Description	Access
`list_events`	List recent server events, newest first	Read-only
`get_event`	Get full details of a specific event	Read-only
`search_events`	Search events by keyword	Read-only
`list_event_subscriptions`	List event subscriptions	Read-only
`create_event_subscription`	Subscribe a notification channel to an event type	Additive
`delete_event_subscription`	Delete an event subscription	Destructive
`list_webhooks`	List configured webhooks	Read-only
`get_webhook`	Get details of a specific webhook	Read-only
`create_webhook`	Create a webhook endpoint	Additive
`update_webhook`	Update a webhook’s configuration	Idempotent write
`delete_webhook`	Permanently delete a webhook	Destructive

Events

Read-only tools for browsing the event log: server activity such as command completions, commits, and sudo usage.

list_events

List recent server events and activity logs, ordered by newest first. Filter by server or reporter to narrow down the log.

Access: Read-only

Parameters

Parameter	Type	Required	Description
`server_id`	string	No	Filter events to a specific server (server UUID)
`reporter`	string	No	Filter events by reporter
`limit`	integer	No	Maximum number of events to return (default: 50)

Example

“What happened on web-01 in the last day?”

The client calls list_events with server_id set to the server’s UUID and summarizes the returned activity.

get_event

Get the full details of a specific event by ID: description, timestamp, associated server, reporter, and event record. Use this after finding an event of interest through list_events or search_events.

Access: Read-only

Parameters

Parameter	Type	Required	Description
`event_id`	string	Yes	ID of the event to retrieve

Example

“Show me the full details of that last commit event.”

The client calls get_event with the event’s ID and returns its complete record.

search_events

Search events by keyword across server name, reporter, record, and description fields. Optionally restrict the search to a specific server.

Access: Read-only

Parameters

Parameter	Type	Required	Description
`search_query`	string	Yes	Keyword to search for
`server_id`	string	No	Restrict the search to a specific server (server UUID)
`limit`	integer	No	Maximum number of results to return (default: 20)

Example

“Search the event log for anything mentioning sudo on db-01.”

The client calls search_events with search_query="sudo" and server_id set to db-01’s UUID.

Event subscriptions

Event subscriptions define which events (command_fin, servers_commit, sudo, and more—see Metric threshold events for the two metric alert types) trigger a notification to a channel, such as a webhook. Each user can only manage their own subscriptions.

list_event_subscriptions

List event subscriptions in the workspace: subscription ID, channel, event type, and target ID.

Access: Read-only

Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Number of items per page

Example

“What event subscriptions do I currently have set up?”

The client calls list_event_subscriptions and lists each subscription’s channel and event type.

create_event_subscription

Create an event subscription to receive notifications when a specific event type occurs. Requires a notification channel ID (for example, a webhook ID from list_webhooks) and an event type. Optionally filter to a specific target resource.

Access: Additive

Parameters

Parameter	Type	Required	Description
`channel`	string	Yes	ID of the notification channel to deliver events to (for example, a webhook ID)
`event_type`	string	Yes	Event type to subscribe to, e.g. `command_fin`, `servers_commit`, `sudo`, `metric_threshold_crossed`, `metric_threshold_resolved`. The tool passes this straight through—it doesn’t validate or enumerate the supported types
`target_id`	string	No	Restrict the subscription to a specific target resource ID

Example

“Subscribe our ops webhook to sudo events.”

The client calls list_webhooks to find the webhook’s ID, then calls create_event_subscription with channel set to that ID and event_type="sudo".

delete_event_subscription

Delete an event subscription by its ID to stop receiving notifications for that event type. You can only delete your own subscriptions.

Access: Destructive

Parameters

Parameter	Type	Required	Description
`subscription_id`	string	Yes	ID of the event subscription to delete

Example

“Stop sending sudo notifications to the ops webhook.”

The client finds the matching subscription with list_event_subscriptions, then calls delete_event_subscription with its ID.

Metric threshold events

Two event types carry an alert rule’s alerts to whatever channel points at—a webhook, or any other notification channel: metric_threshold_crossed when a rule’s threshold is breached (or the metric goes silent past its no-data window), and metric_threshold_resolved when that alert later clears.

Subscribing to either requires the Metrics extension—Essentials and Enterprise workspaces can turn it on, Free can’t (see Monitor server status). If the extension is turned off after you’ve subscribed, the subscription stops receiving metric_threshold_crossed but keeps receiving metric_threshold_resolved, so an alert you were already tracking always gets its closing event.

Both events carry the same alert_id, so a relay pairs a metric_threshold_resolved with the metric_threshold_crossed that opened it by matching that field.

metric_threshold_crossed

json

{
  "event": "metric_threshold_crossed",
  "alert_id": "9a1c0b62-9f3a-4a3d-8a1e-2b0f2c6d5e41",
  "reason": "threshold",
  "rule": {
    "id": "4f2b18d0-5c77-4a0b-9d2e-1f7a3c9b4e05",
    "name": "cpu-high",
    "target": "cpu-usage",
    "operator": "gte",
    "threshold": 80.0,
    "duration_s": 300,
    "severity": "warning"
  },
  "server": { "id": "7c5e2a41-6b90-4c33-a7d8-0e5f1b2c3d44", "name": "web-01" },
  "device": null,
  "observed": {
    "value": 92.3,
    "window_start": "2026-09-01T11:55:00+00:00",
    "window_end": "2026-09-01T11:59:30+00:00"
  },
  "started_at": "2026-09-01T12:00:00+00:00",
  "workspace": "acme",
  "link": "https://acme.us1.alpacon.io/servers/7c5e2a41-6b90-4c33-a7d8-0e5f1b2c3d44"
}

metric_threshold_resolved

json

{
  "event": "metric_threshold_resolved",
  "alert_id": "9a1c0b62-9f3a-4a3d-8a1e-2b0f2c6d5e41",
  "reason": "threshold",
  "rule": {
    "id": "4f2b18d0-5c77-4a0b-9d2e-1f7a3c9b4e05",
    "name": "cpu-high",
    "target": "cpu-usage",
    "operator": "gte",
    "threshold": 80.0,
    "duration_s": 300,
    "severity": "warning"
  },
  "server": { "id": "7c5e2a41-6b90-4c33-a7d8-0e5f1b2c3d44", "name": "web-01" },
  "device": null,
  "observed": {
    "value": 41.2,
    "window_start": "2026-09-01T12:05:00+00:00",
    "window_end": "2026-09-01T12:05:00+00:00"
  },
  "started_at": "2026-09-01T12:00:00+00:00",
  "workspace": "acme",
  "link": "https://acme.us1.alpacon.io/servers/7c5e2a41-6b90-4c33-a7d8-0e5f1b2c3d44",
  "cause": "recovered",
  "resolved_at": "2026-09-01T12:05:00+00:00",
  "open_for_s": 300
}

Fields

Field	Meaning
`alert_id`	Identifies this alert. The same value appears on the `metric_threshold_crossed` event that opened it and the `metric_threshold_resolved` event that closes it.
`reason`	`threshold`—the rule’s threshold was crossed—or `no_data`—the metric stopped arriving.
`rule`	The rule that fired, with the server’s own overrides already applied: `id`, `name`, `target` (the metric it watches), `operator` (`gte` or `lte`), `threshold`, `duration_s`, `severity`. See What a rule can carry for what each of these fields means. On a resolved event, this describes the rule as it stands now and is `null` if the rule has since been deleted—for what fired, use the crossed event with the same `alert_id`.
`server`	The server the alert is about: `id` and `name`.
`device`	The disk or network interface the rule is scoped to, or `null` for a host-wide rule.
`observed`	The samples behind this edge: `value` is the latest one, and `window_start`/`window_end` bound the samples the evaluation actually read. `null` when `reason` is `no_data`.
`started_at`	When the alert was first raised.
`workspace`	Your workspace slug.
`link`	The server’s page in the console.
`cause` (resolved only)	Why the alert closed: `recovered` (the metric returned past its recovery threshold, or the rule’s own threshold if none is set), `no_data_cleared` (the server started reporting again), `rule_detached` (the rule was deleted, or the server was detached from it), `rule_changed` or `scope_narrowed` (the rule no longer covers this server or device), `override_disabled` (a per-server override exempted it), `server_disabled` (the server is no longer managed), `not_evaluated` (no rule covers it anymore), `superseded` (a per-device alert replaced a host-wide one), `device_removed` (the device is no longer reported by the server), or `unknown` (the condition no longer applies, for a resolution that couldn’t be traced to a more specific cause).
`resolved_at` (resolved only)	When the alert closed.
`open_for_s` (resolved only)	How long the alert was open, in seconds—not to be confused with `rule.duration_s`, which is how long the condition had to hold before the alert was raised in the first place.

Webhooks

Webhooks are endpoints that receive HTTP callbacks when subscribed events occur. Listing, creating, updating, and deleting webhooks all require admin permission.

list_webhooks

List configured webhooks in the workspace: webhook ID, name, URL, SSL verification setting, and enabled status. Requires admin permission.

Access: Read-only

Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination
`page_size`	integer	No	Number of items per page

Example

“List all the webhooks configured in this workspace.”

The client calls list_webhooks and returns each webhook’s name, URL, and enabled status.

get_webhook

Get detailed information about a specific webhook by ID: name, URL, SSL verification setting, enabled status, and owner.

Access: Read-only

Parameters

Parameter	Type	Required	Description
`webhook_id`	string	Yes	ID of the webhook to retrieve

Example

“Show me the details of the ops webhook.”

The client calls get_webhook with the webhook’s ID and returns its full configuration.

create_webhook

Create a webhook endpoint to receive HTTP callbacks when subscribed events occur. Requires a name and URL; SSL verification and enabled status are optional. Requires admin permission.

Access: Additive

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Name of the webhook
`url`	string	Yes	URL to receive webhook callbacks
`ssl_verify`	boolean	No	Verify SSL certificates on the callback URL (default: `true`)
`enabled`	boolean	No	Whether the webhook is enabled (default: `true`)

Example

“Create a webhook called ‘ops-alerts’ pointing to our incident bot’s URL.”

The client calls create_webhook with name="ops-alerts" and the given url.

update_webhook

Update an existing webhook’s configuration by ID. Only the fields you provide are updated (partial update). Requires admin permission.

Access: Idempotent write

Parameters

Parameter	Type	Required	Description
`webhook_id`	string	Yes	ID of the webhook to update
`name`	string	No	New name for the webhook
`url`	string	No	New callback URL
`ssl_verify`	boolean	No	Verify SSL certificates on the callback URL
`enabled`	boolean	No	Whether the webhook is enabled

Example

“Disable the ops-alerts webhook for now.”

The client calls update_webhook with the webhook’s ID and enabled=false.

delete_webhook

Permanently delete a webhook endpoint by ID. This stops all HTTP callbacks for subscriptions using this webhook. Requires admin permission.

Access: Destructive

Parameters

Parameter	Type	Required	Description
`webhook_id`	string	Yes	ID of the webhook to delete

Example

“Delete the old ops-alerts webhook, we don’t use it anymore.”

The client calls delete_webhook with the webhook’s ID. Any subscriptions still pointing at it stop delivering.

Monitoring & alerts tools: Metrics, alert rules, and alert management
Audit logs tools: Activity logs, server logs, and WebFTP transfer logs

Events & webhooks tools

Summary#

Events#

list_events#

Parameters#

Example#

get_event#

Parameters#

Example#

search_events#

Parameters#

Example#

Event subscriptions#

list_event_subscriptions#

Parameters#

Example#

create_event_subscription#

Parameters#

Example#

delete_event_subscription#

Parameters#

Example#

Metric threshold events#

metric_threshold_crossed#

metric_threshold_resolved#

Fields#

Webhooks#

list_webhooks#

Parameters#

Example#

get_webhook#

Parameters#

Example#

create_webhook#

Parameters#

Example#

update_webhook#

Parameters#

Example#

delete_webhook#

Parameters#

Example#

Related#

Summary

Events

list_events

Parameters

Example

get_event

Parameters

Example

search_events

Parameters

Example

Event subscriptions

list_event_subscriptions

Parameters

Example

create_event_subscription

Parameters

Example

delete_event_subscription

Parameters

Example

Metric threshold events

metric_threshold_crossed

metric_threshold_resolved

Fields

Webhooks

list_webhooks

Parameters

Example

get_webhook

Parameters

Example

create_webhook

Parameters

Example

update_webhook

Parameters

Example

delete_webhook

Parameters

Example

Related