Notifications & activity

Four channels, in increasing order of push:

Channel	Audience	Latency	Use for
Activity feed	anyone with read access	immediate	“what happened here?”
In-app notifications	one user	seconds	invitations, quota warnings, failures
Email	one user	seconds	things that matter when you’re not looking
Webhooks	your systems	seconds	automation

Activity feeds

Every meaningful action is appended to the repository’s event log, and the organization feed is the union across its repositories.

export API=https://cavsnode.com/api/v1
export H="Authorization: Bearer $CAVS_TOKEN"

# One repository
curl -sS "$API/repositories/$REPO/activity?limit=50&skip=0" -H "$H"

# Filter by event type or actor
curl -sS "$API/repositories/$REPO/activity?type=push&limit=20"        -H "$H"
curl -sS "$API/repositories/$REPO/activity?actor=$USER_ID&limit=20"   -H "$H"

# Organization-wide, optionally narrowed to one repository
curl -sS "$API/organizations/acme-ai/activity?limit=100"        -H "$H"
curl -sS "$API/organizations/acme-ai/activity?repo=$REPO"       -H "$H"

Parameter	Range	Default
limit	1–200	50
skip	0–10000	0
type	an event type	all
actor	a user id	all
repo	a repository UUID (org feed only)	all

Typical entries: pushes with their generation, index finalizations, releases, snapshots, repository creation and settings changes, member and collaborator changes, token creation and revocation.

Note

The activity feed is a product feed — readable by anyone with repository access. The audit log is a separate, admin-only, security-oriented record with actor, IP and structured metadata. Use activity to understand work, audit to answer compliance questions.

In-app notifications

Per-user, shown in the dashboard’s bell menu.

curl -sS "$API/notifications" -H "$H"
curl -sS -X POST "$API/notifications/$ID/read" -H "$H"

You get one for: an invitation to an organization or a repository, a storage quota warning or breach, a storage connection turning unhealthy or recovering, a webhook auto-disabled after repeated failures, and billing events such as a failed payment.

Email

The same events that raise a notification also send an email when they’re worth interrupting someone for — invitations above all, then quota breaches, connection failures and payment problems.

Delivery in production runs through Mailgun; a self-hosted deployment can use SMTP or log-only. See Configuration reference.

Tip

If an invitation email never arrives, check the spam folder, then have an admin regenerate the link from Settings → Members → Invitations and share it directly. The link is the invitation; email is only the transport.

Webhooks

The programmable channel: signed HTTP POSTs to your endpoint when something happens. Configure them per organization at Settings → Webhooks.

curl -sS -X POST "$API/organizations/acme-ai/webhooks" \
  -H "$H" -H "Content-Type: application/json" \
  -d '{
        "url": "https://hooks.example.com/cavs",
        "events": ["repository.push", "release.published", "storage.quota.warning"]
      }'

The response contains a generated signing secret (whsec_…), shown once. Store it — you need it to verify deliveries.

Nine public event types are available — repository.created, repository.deleted, repository.push, repository.push.indexed, release.published, storage.snapshot.created, storage.quota.warning, storage.quota.exceeded, maintenance.gc.completed. Everything else is internal and never leaves the platform.

Each delivery carries X-CAVS-Event, X-CAVS-Delivery and X-CAVS-Signature: sha256=<hmac>. Verify the signature before acting on a payload. Full detail, retry policy, the circuit breaker and verification code in several languages: Webhooks.

Choosing a channel

You want to…	Use
See who pushed what, in context	activity feed
Be told when a quota is about to bite	notifications + email
Trigger a deploy when a release is tagged	webhook on release.published
Kick off a downstream job after new data lands	webhook on repository.push
Answer “who deleted this, and from where?”	audit log
Alert on platform health (self-hosted)	Prometheus metrics

Next

• Webhooks — payloads, signing, retries.
• Event catalog — every event, internal and public.
• Audit log — the security-grade record.