Events Management
Required Permissions: Admin or SuperUser role
Security Level: Medium
Estimated Time: 12 minutes
Events Management is the operational hub for your tenant's event processing pipeline. You use it to inspect events flowing through the system, manage subscriptions that route events to webhooks, internal handlers, or message queues, track delivery status, create webhook templates for popular platforms, and monitor the system in real time. Access it at Admin Portal → Events Management.
Prerequisites
- Your account holds an Admin or SuperUser role.
- Your tenant has provisioned infrastructure stacks (events are scoped to stacks).
Overview
The Events Management page opens with four overview cards — Total Events, Events (24h), Active Subscriptions, and Failed Deliveries (24h) — giving you an immediate sense of throughput and health.
Below the overview cards, a tabbed interface organizes the functionality:
| Tab | Purpose |
|---|---|
| Events | Browse, filter, and inspect all events processed by the platform. |
| Subscriptions | View event subscriptions that route events to webhooks, internal handlers, or queues. |
| Deliveries | Track the delivery status of events dispatched to subscriptions. |
| Webhook Templates | Create and manage payload transformation templates for webhook deliveries. |
| Real-time Monitoring | Live WebSocket stream of events, system health, and delivery updates. |
| Platform Overview | (SuperUser only) Platform-wide health checks, stuck event cleanup, and dead letter management. |
Stack filtering
If your tenant has multiple infrastructure stacks, use the Stack Filter dropdown at the top of the page to scope all data to a specific stack. Events, subscriptions, and deliveries are stack-aware; webhook templates are tenant-wide and not affected by the filter.
Events Tab
The Events tab shows a paginated table of every event processed by the platform.
Table columns
| Column | What it shows |
|---|---|
| Event Type | The event identifier (e.g., file.uploaded, chat.message.sent) and subject. |
| Source | The system component that generated the event. |
| Status | Current processing state — Queued, Processing, Succeeded, Failed, or Dead Letter. |
| Attempts | Number of processing attempts out of the maximum allowed. |
| Deliveries | How many subscription deliveries were dispatched for this event. |
| Created | Timestamp when the event was created. |
Filtering and sorting
- Filter by Event Type — free-text search on event type names.
- Status — filter to a specific status (Queued, Processing, Succeeded, Failed, Dead Letter).
- Sort Order — Newest First or Oldest First.
- Refresh — reload the data from the server.
Event details
Click the View Details icon on any event row to open a dialog showing the full event record: ID, type, source, subject, status, priority, attempt history, payload JSON, timestamps, and any error messages.
Subscriptions Tab
Event subscriptions define how events are routed when they occur. Each subscription matches an event pattern and delivers to a target.
Subscription types
| Type | How it works |
|---|---|
| Webhook | Sends an HTTP POST to a configured URL. Supports custom headers, timeouts, and webhook templates. |
| Internal | Routes the event to an internal handler function within the platform. |
| Queue | Publishes the event to a message queue (Azure Service Bus, AWS SQS, Kafka, or RabbitMQ). |
Source tracking
Each subscription shows its source — who created it:
- User — manually created by an administrator.
- Scheduler — automatically created by a scheduled task (shown with a lock icon and linked schedule name).
- System — created by the platform itself.
Managed subscriptions (created by the scheduler or system) are marked with a lock icon. They should generally not be modified manually to avoid conflicts with the owning system.
Managing subscriptions
The Manage Subscriptions button navigates to the dedicated subscription management page at /admin-portal/events/subscriptions, where you can:
- Create a new subscription — choose an event pattern (or select specific event types), a subscription type, and configure the target (webhook URL, handler function, or queue provider).
- Edit an existing subscription — modify its event pattern, target configuration, rate limits, or active state.
- Delete a subscription — with an option to also delete the associated message queue for queue-type subscriptions.
- Test a subscription — send a test event to verify delivery.
- View connection details — for queue subscriptions, retrieve the connection string, namespace, and queue name.
Rate limiting
Each subscription can have a rate limit (requests per minute) to prevent overwhelming the target endpoint. The default is 100 per minute.
Deliveries Tab
The Deliveries tab tracks every delivery attempt for every subscription.
Delivery statuses
| Status | Meaning |
|---|---|
| Pending | Delivery is queued and waiting to be dispatched. |
| Dispatched | Delivery has been sent to the target. |
| Delivered | Target acknowledged receipt (HTTP 2xx response for webhooks). |
| Failed | Delivery attempt failed (target returned an error or was unreachable). |
| Skipped | Delivery was intentionally skipped (e.g., subscription was inactive). |
| Dead Letter | All retry attempts exhausted — the delivery is moved to dead letter for investigation. |
Filtering
- Filter by Event Type — narrow by the originating event type.
- Filter by Subscription — search by subscription name.
- Status — filter to a specific delivery status.
Delivery details
Click View Details on any delivery row to see the full record: event type, subscription name, status, attempt count, response status code, scheduled and delivered timestamps, and any error message.
Webhook Templates
Webhook templates define how event payloads are transformed before delivery. You can use built-in formats for popular platforms or write custom templates.
Template types
| Type | Format |
|---|---|
| Default | Sends the raw event payload as-is. |
| Slack | Transforms the payload into Slack message format. |
| Teams | Transforms the payload into Microsoft Teams message format. |
| Discord | Transforms the payload into Discord webhook format. |
| Custom | Uses a user-defined template body for arbitrary transformation. |
Managing templates
- Create Template — specify a name, description, transformer type, and optional template body (for custom templates).
- Activate/Deactivate — toggle a template's active state. Inactive templates are not used even if assigned to a subscription.
- View Details — inspect the template body, creation date, creator, and how many subscriptions reference it.
Templates are tenant-wide — they are not scoped to a specific infrastructure stack.
Real-time Monitoring
The Real-time Monitoring tab provides a live WebSocket connection to the event processing system.
Connecting
Click Connect to establish the WebSocket connection. The connection status indicator shows whether you are connected (green) or disconnected (red). Click Disconnect to close the connection when you are done monitoring.
System health
Once connected, the system health panel shows:
- Health Score — a percentage indicating overall system health.
- Stuck Events — events that are not progressing through the pipeline.
- Error Rate — percentage of recent events that resulted in errors.
- Delivery Failure Rate — percentage of deliveries that failed.
- Recent Events Processed — count of events processed recently.
- Alerts — any active warning or critical alerts from the system.
Live events
A real-time feed shows events as they are processed, including their type, status, tenant, source, and timestamp. The feed keeps the most recent 100 events.
Delivery updates
A live feed of delivery status changes — showing which subscription received which event, the delivery status, and attempt count.
Tip: Use real-time monitoring during deployment or incident investigation to observe event flow and spot delivery failures immediately.
Platform Overview (SuperUser Only)
SuperUsers see an additional tab with platform-wide tools:
- Health Check — run a platform-wide health check across all tenants.
- Clear Stuck Events — clean up events that are stuck in processing state.
- Dead Letter Management — inspect and retry or discard dead-lettered events and deliveries.
- Cleanup Tools — purge old events and deliveries to manage storage.
Best Practices
- Monitor the Failed Deliveries (24h) card regularly. A rising number usually indicates a webhook endpoint that is down or misconfigured.
- Use webhook templates for Slack, Teams, or Discord notifications rather than building custom integrations — they handle the formatting automatically.
- Set appropriate rate limits on subscriptions targeting external services to avoid being throttled or blocked.
- For queue-type subscriptions, use the connection details feature to securely share credentials with consuming applications.
- Use real-time monitoring during incident response to see event flow and delivery failures as they happen.
- Do not manually modify managed subscriptions (marked with a lock icon) — they are controlled by the scheduler or system and may be overwritten.
Troubleshooting
Events stuck in "Processing" status If events are stuck, the background processing task may have stalled. Refresh the page to confirm, then check the Real-time Monitoring tab for system health. SuperUsers can use the Clear Stuck Events tool on the Platform Overview tab.
Webhook deliveries failing Check the delivery detail for the response status code and error message. Common causes include: the target URL is unreachable, the endpoint returns non-2xx responses, or the webhook secret/headers are misconfigured.
Subscription not receiving events Verify the subscription is Active. Check the event pattern matches the events you expect. If the subscription was recently created, new events may take a moment to route.
Dead letter events accumulating Dead-lettered events have exhausted all retry attempts. Review the error messages to understand the root cause (usually a permanently failing endpoint), then fix the subscription configuration and retry or discard the dead letters.
Cannot connect to real-time monitoring Ensure your browser supports WebSocket connections and that no firewall or proxy is blocking them. Try refreshing the page and clicking Connect again.
Next Steps
For managing the infrastructure stacks that events flow through, see Infrastructure Management. For an overview of all admin portal capabilities, see Admin Portal Overview.
Related Topics
⏱️ Read time: 12 minutes | 📊 Difficulty: intermediate