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:

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

All Vigilhold docs · Start a 14-day free trial