Webhooks & Audit Logs

Catalyst Networks gives you two ways to keep tabs on what happens in your network: webhooks push events to your own services in real time, and the activity log shows a recent history of changes inside the dashboard. Both are organization-scoped.

Webhooks

A webhook is an HTTP endpoint you register to receive a JSON POST whenever a subscribed event occurs in your organization. They live under /organizations/<slug>/webhooks/. Viewing the list is open to any member; creating, editing, and deleting webhooks require the owner or admin role.

Creating a webhook

From Webhooks (/organizations/<slug>/webhooks/) choose Create (create/) and provide:

Field	Purpose
URL	The HTTPS endpoint that will receive event POSTs.
Events	One or more event types to subscribe to (see the catalog below).
Description	Optional note describing the webhook.
Secret	Optional shared secret you can store to authenticate deliveries.
Active	Whether the webhook is enabled. Inactive webhooks are skipped at delivery time.

Edit a webhook at <pk>/edit/ and remove it at <pk>/delete/.

Event catalog

The following event types can be subscribed to:

Category	Events
Nodes	node.added, node.removed
Certificates	cert.issued, cert.revoked, cert.expiring, cert.renewed
Groups (tags)	group.created, group.updated, group.deleted
Policies (firewall rules)	policy.created, policy.updated, policy.deleted
Network	ip.allocated
Members	member.created, member.updated, member.deleted
Security	security.brute_force

How delivery works

Most events are raised automatically by the platform. Node, tag (group), firewall-rule (policy), and membership changes fire from database signals as they happen; certificate events fire from the certificate lifecycle tasks. When an event fires, it fans out asynchronously (through Celery) to every active webhook in the organization that subscribes to that event type.

Each delivery is an HTTP POST with a JSON body of the form:

{
  "event": "node.added",
  "organization_id": 42,
  "timestamp": "2026-07-03T12:00:00+00:00",
  "data": { }
}

The data object carries event-specific details (for example the node name and Nebula IP for node.added). Deliveries use a short request timeout and are retried with exponential backoff if the endpoint returns an error or is unreachable, so your receiver should be idempotent.

Test and delivery-log UI are not complete in this build

In the current customer-app codebase the per-webhook Test action (<pk>/test/) and the Delivery Logs page (logs/) are placeholder stubs: the test endpoint redirects without sending a request, and the logs view renders an empty list. The data model for recording deliveries (WebhookDelivery) exists but is not populated in this build. Treat the event catalog and delivery pipeline above as authoritative, but do not rely on the Test button or Logs page yet — verify against your deployment if these have been completed there.

Activity Log

The activity log is a lightweight, in-dashboard record of recent changes, reached at /organizations/<slug>/activity/. It is backed by django-simple-history, which transparently writes a versioned history row every time a tracked object is created, changed, or deleted.

What the activity page shows

The activity page surfaces a merged, most-recent-first feed of node and security-group (tag) changes — the latest created and updated events for each, capped at the ten most recent entries overall. Each entry shows the kind of change, a short human-readable message, and a timestamp, for example:

• Node “db-1” was created.
• Security group “web” was updated.

It gives you an at-a-glance answer to “what changed recently on this network?” without leaving the dashboard.

What is tracked underneath

The history tables capture far more than the activity page renders. Models across the platform carry history tracking, including:

Area	Tracked models
Nodes	Node
Organizations	Organization, NetworkRange, Membership, Invitation
Security groups	Tag (security group), FirewallRule
Certificates	Certificate
Webhooks	Webhook, WebhookDelivery
Other	Users, plans, notifications, SSO, and support records

Each history row records the timestamp, the change type (created, changed, or deleted), and — when available — the acting user, giving you a durable audit trail. This full history is retained in the database (and reachable through the Django admin) even though the dashboard’s activity page intentionally shows only the recent node and security-group highlights.

What an admin can learn

• Recency — what changed on the network most recently, and when.
• Object lifecycle — when nodes and groups were created or last modified.
• Accountability — the underlying history preserves who made changes (where a user is attributed), useful for after-the-fact review of configuration drift or unexpected changes.

Next Steps

• Web Dashboard Overview — where webhooks and activity sit in the dashboard
• Security Groups & Firewall Policies — the group and policy changes that raise group.* and policy.* events