API: Event Ingest
Push custom events from external systems into the Vigilhold timeline and webhook pipeline.
POST /api/events/ingest — push a custom event
Record an event from any external system — a deploy, a cron result, a CI run. It is stored for the events API, sent on the live event stream (/api/stream, as custom_event), and delivered to webhooks subscribed to custom.event. It does not appear in the dashboard.
Required scope: events:write
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source": "github-actions",
"type": "deploy.completed",
"title": "Deployed api-service v2.4.1",
"body": "SHA: a3f9c1d — 23 files changed",
"severity": "success",
"server_id": "4f2a9c1e8b7d6a50",
"meta": { "version": "2.4.1", "sha": "a3f9c1d" }
}' \
https://vigilhold.com/api/events/ingest
Field reference:
- Field — Required — Description
- source — ✓ — Originating system label (max 64 chars)
- type — ✓ — Event type: lowercase letters, digits, dots, dashes or underscores, e.g. deploy.completed
- title — ✓ — Short human-readable title (max 200 chars)
- body — — — Optional detail text
- severity — — — info (default), warning, error, success
- server_id — — — A server's id (e.g. 4f2a9c1e8b7d6a50), to tie the event to that server
- meta — — — Arbitrary JSON object for extra context
GET /api/events — list historical events
Returns the custom events your organization has pushed, newest first.
Required scope: events:read
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://vigilhold.com/api/events?limit=50&type=deploy.completed"
Query params: limit (default 50, max 500), offset, type, source, severity, server_id, since and until (milliseconds since the epoch).
Response:
{
"events": [
{
"id": 9121,
"source": "github-actions",
"type": "deploy.completed",
"title": "Deployed api-service v2.4.1",
"body": "SHA: a3f9c1d — 23 files changed",
"severity": "success",
"server_id": "4f2a9c1e8b7d6a50",
"meta": { "version": "2.4.1" },
"created_at": 1792548912456
}
],
"total": 142,
"limit": 50,
"offset": 0,
"has_more": true
}
GET /api/events/sources and GET /api/events/types list the sources and types you have used.
Webhook integration
Every pushed event is delivered to webhook endpoints subscribed to custom.event or *, with its source, type, severity and meta in data. Subscriptions are by event name, so filter on data.type at your end (for example, only deploy.*).
That makes Vigilhold one place to send deploys, cron results and CI outcomes, alongside its own alerts, to whatever already receives your webhooks.
Tips
- Use type namespacing to keep events organized: deploy.started, deploy.completed, deploy.failed.
- Set server_id to tie an event to a server, so you can filter by it later.