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.
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) 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: command_fin, servers_commit, or sudo |
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.
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.
Related
- Monitoring & alerts tools: Metrics, alert rules, and alert management
- Audit logs tools: Activity logs, server logs, and WebFTP transfer logs