Introduction

What is Vela?

Vela sits between your application and your team’s alerting tools. You send structured events from your backend — Vela validates them, stores them, evaluates your notification rules, and delivers alerts to the right channels automatically. The problem Vela solves: Most teams duct-tape event tracking together with scattered log statements, hardcoded Slack messages, and cron jobs polling the database. When something breaks at 2am, there’s no single place to look. Vela gives you that place.

How it works

Define your event schemas

Describe the shape of events your application produces. Vela validates every incoming event against its schema — invalid data is rejected at the door before it can pollute your system.

{
  "eventName": "order.placed",
  "fields": [
    { "id": "f1", "name": "orderId",     "type": "string", "required": true },
    { "id": "f2", "name": "amountCents", "type": "number", "required": true }
  ]
}

Send events from your backend

One SDK call. Vela handles validation, storage, and routing.

import { VelaIngestClient } from '@vela-event/sdk';

const vela = new VelaIngestClient(process.env.VELA_API_KEY);

await vela.ingest({
  event: 'order.placed',
  data: { orderId: 'ord_123', amountCents: 4999 },
  level: 'info',
});

Set up notification rules

Define which events trigger alerts and where they go — no code changes needed. Rules are managed in the dashboard and can match on any payload field.Example: “When payment.failed arrives with amountCents > 10000, post to #alerts on Slack.”

Core concepts

Concept	Description
App	An isolated workspace that owns schemas, events, and rules. One app per service or environment.
Schema	Defines the fields an event must contain. Enforced at ingest time — invalid payloads are rejected with `400`.
Event	A structured payload sent to Vela. Validated, stored, and routed through the rules engine.
Notification Rule	A condition-based trigger. Fires when an event matches, then routes to a destination.
Destination	Where alerts are sent — Slack, Discord, Email, or a custom webhook.

Choose your integration

TypeScript SDK

Zero-dependency client for Node.js 18+. Full TypeScript types. Works in browsers and edge runtimes.

Python SDK

Sync and async support via httpx. Python 3.9+. Fully typed.

CLI

Manage schemas as JSON files, version-control them, push to Vela. Like Prisma for your events.

Quick links

Quickstart

Send your first event in under 5 minutes.

Core Concepts

Understand apps, schemas, events, and rules in depth.

API Reference

Full HTTP API docs with curl examples.

Credentials

Client secrets vs API keys — when to use each.

Self-hosting

Vela is fully open source under AGPL-3.0. The only dependencies are PostgreSQL and RabbitMQ — both included in the Docker Compose file.

git clone https://github.com/vela-event/vela.git
cd vela
cp .env.sample .env
docker compose -f docker-compose.infra.yml up -d
pnpm install && pnpm migration:run && pnpm start:dev

API available at http://localhost:3000. Swagger docs at http://localhost:3000/docs.

​What is Vela?

​How it works

​Core concepts

​Choose your integration