REST API

Ingestion Service

The Ingestion Service runs on https://ingest.vigilry.com and accepts events from your applications. All endpoints require an API key via the X-Api-Key header. Events are published to Redis Streams and processed asynchronously.

API Key Authentication

All ingestion endpoints require an X-Api-Key header with a valid project API key. The project context is derived from the key — you do not need to pass a project ID separately.

X-Api-Key: vig_live_abc123def456...

POST/ingest/events

Send a custom event. Use this for business-level observations — feature flags, checkout flows, critical paths, etc.

Auth:API Key (X-Api-Key header)

Request Body

Name	Type	Required	Description
`type`	string	required	Event type identifier (e.g. checkout_started, feature_disabled).
`severity`	"INFO" \| "WARN" \| "ERROR" \| "CRITICAL"	required	Severity level (uppercase).
`message`	string	required	Human-readable event description.
`source`	string	optional	Service or component name (e.g. payment-service).
`correlation`	object	optional	Key-value context for grouping related events (user_id, order_id, etc.).
`payload`	object	optional	Arbitrary additional metadata.

POST /ingest/events HTTP/1.1
X-Api-Key: vig_live_abc123...
Content-Type: application/json

{
  "type": "checkout_failed",
  "severity": "ERROR",
  "message": "Payment gateway returned 402",
  "source": "checkout-service",
  "correlation": {
    "user_id": "usr_99",
    "order_id": "ord_4421"
  },
  "payload": {
    "gateway": "stripe",
    "code": "card_declined"
  }
}

HTTP/1.1 202 Accepted

{
  "jobId": "bull-123456",
  "status": "queued"
}

POST/ingest/server-error

Report an unhandled server-side error. Automatically extracts stack trace, HTTP method, path, and status code.

Auth:API Key (X-Api-Key header)

Request Body

Name	Type	Required	Description
`status_code`	number	required	HTTP status code (e.g. 500).
`path`	string	required	Request path where the error occurred.
`method`	string	required	HTTP method (GET, POST, etc.).
`error_message`	string	required	Error message string.
`stack`	string	optional	Stack trace (optional but recommended).
`correlation`	object	optional	Correlation context (user_id, order_id, etc.).

POST /ingest/server-error HTTP/1.1
X-Api-Key: vig_live_abc123...
Content-Type: application/json

{
  "status_code": 500,
  "path": "/api/orders",
  "method": "POST",
  "error_message": "Cannot read properties of undefined",
  "stack": "TypeError: Cannot read properties of undefined\n  at processOrder (/app/orders.js:42:15)",
  "correlation": {
    "user_id": "usr_99",
    "order_id": "ord_4421"
  }
}

HTTP/1.1 202 Accepted

{
  "jobId": "bull-123457",
  "status": "queued"
}

POST/ingest/webhook

Forward an incoming webhook payload as an event. Useful for tracking third-party system notifications.

Auth:API Key (X-Api-Key header)

Request Body

Name	Type	Required	Description
`source`	string	required	Webhook source name (e.g. github, pagerduty).
`event`	string	required	Event name from the webhook provider.
`payload`	object	required	The full webhook payload.
`severity`	"INFO" \| "WARN" \| "ERROR" \| "CRITICAL"	optional	Severity override. Defaults to INFO.

POST /ingest/webhook HTTP/1.1
X-Api-Key: vig_live_abc123...
Content-Type: application/json

{
  "source": "github",
  "event": "push",
  "severity": "INFO",
  "payload": {
    "ref": "refs/heads/main",
    "pusher": { "name": "alice" }
  }
}

HTTP/1.1 202 Accepted

{
  "jobId": "bull-123458",
  "status": "queued"
}

POST/ingest/stripe

Ingest a Stripe webhook event. Automatically maps Stripe event types to Vigilry severity levels.

Auth:API Key (X-Api-Key header)

Stripe payment_failed and charge.failed events are mapped to ERROR severity. Other events default to INFO.

Request Body

Name	Type	Required	Description
`type`	string	required	Stripe event type (e.g. payment_intent.payment_failed).
`data`	object	required	Stripe event data object.
`id`	string	optional	Stripe event ID for deduplication.

POST /ingest/stripe HTTP/1.1
X-Api-Key: vig_live_abc123...
Content-Type: application/json

{
  "id": "evt_1ABC...",
  "type": "payment_intent.payment_failed",
  "data": {
    "object": {
      "id": "pi_1ABC...",
      "amount": 2999,
      "currency": "usd",
      "last_payment_error": {
        "code": "card_declined"
      }
    }
  }
}

HTTP/1.1 202 Accepted

{
  "jobId": "bull-123459",
  "status": "queued"
}