Skip to main content

Authoring notification policies

Every event is stored regardless of policy (see Policies). This guide walks through making one also notify someone, as a tenant-admin.

1. Create a rule​

curl -s -X POST "$CNS_API/admin/v1/policies" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "event_type": "invoice.paid",
        "notify": true,
        "delivery": "instant",
        "channels": ["inapp"],
        "extra_recipients": ["sub_finance_team"]
      }'

POST upserts — posting the same event_type again replaces the existing rule. Use PUT /admin/v1/policies/{event_type} if you'd rather the path (not the body) pick which rule you're editing.

2. Set a tenant-wide default (optional)​

The literal event type "*" is the tenant's fallback rule, evaluated when no exact event_type match exists:

curl -s -X POST "$CNS_API/admin/v1/policies" \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{ "event_type": "*", "notify": false }'

Making the default notify: false (the fail-closed choice) means an event type nobody has explicitly configured never surprises anyone with a notification — it's still recorded in the store either way.

3. Emit a matching event and confirm it notified​

Emit an event of that event_type (see Emitting events), then check the tenant-wide delivery log as tenant-admin:

curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  "$CNS_API/admin/v1/notifications?event_type=invoice.paid&limit=5"

Or inspect one subject's own feed — extra_recipients land there the same way a target.subject_ids entry would:

curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  "$CNS_API/admin/v1/notifications/feed/sub_finance_team"

(That per-subject inspector route requires an explicit tenant-admin grant — see Authz planes.)

Notes on channels and delivery​

  • channels is informational in Phase 1 — only the in-app channel is wired, so listing others has no delivery effect yet (see Channels).
  • Omitting delivery falls back to the event's own delivery lane rather than forcing one — set it explicitly if this event_type should always be instant (or always batched) regardless of how it was emitted.

Removing a rule​

curl -s -X DELETE "$CNS_API/admin/v1/policies/invoice.paid" -H "Authorization: Bearer $ADMIN_TOKEN"

Full shapes: API Reference → Admin API.