Event Listeners
Event Listeners route important platform events into automated follow-up work. A listener watches for one event type, applies its configured action, and can create a TOPdesk incident or start an Automation Task with values from the event payload.
Core Concepts
Event automation is built around four concepts:
Event: Something that happened in AZExecute, such as an application request being created, a certificate renewal failing, or an automation task completing.
Event Listener: A rule that decides what to do when a specific event type is received.
Event Data: Structured variables from the event, such as application id, request id, task run id, certificate domain, status, requester, and error details.
Action: The work started by the listener. Current actions are TOPdesk Incident and Automation Task.
Where to Configure Listeners
Operators configure Event Listeners from the Operator navigation. The page uses the same list pattern as other operator pages: hero summary, tab header, search, table, paging, and action buttons.
Open Operator -> Event Listeners.
Use search to filter by listener name, event type, or action type.
Use the listener table to review status, last run, run count, and available options.
Create, edit, disable, or delete listeners from the page actions.
Creating a Listener
The create dialog starts with the shared listener settings. These settings apply to every event type and every action.
Name: Display name shown in the overview and audit trail.
Description: Optional explanation of why the listener exists and what downstream process it starts.
Execution Order: Lower numbers run first when multiple enabled listeners match the same event.
Event: The trigger type that starts the listener.
Action: The operation to run when the event is received.
Enabled: Disabled listeners are saved, but do not run when events are created.
Supported Event Triggers
Event triggers are intentionally explicit. This keeps listener behavior predictable and makes it clear which payload values are available for each event type.
Application Requests
Application Request Created: A new application request has been submitted.
Application Request Approved: A request has been approved and can trigger provisioning, ticket updates, or notifications.
Application Request Rejected: A request has been rejected and can trigger ticket closure or requester follow-up.
Applications and Credentials
Application Created: An application entity has been created in AZExecute.
Application Updated: An application entity has changed and may need validation, tagging, or governance checks.
Application Credential Expiring: A known application credential is approaching expiry.
Application Credential Renewed: A credential renewal completed successfully.
Application Credential Renewal Failed: Credential renewal failed and should normally create an incident or remediation task.
Certificates
Certificate Renewal Completed: ACME renewal completed and the certificate payload can be passed to deployment automation.
Certificate Renewal Failed: Renewal failed and can create a TOPdesk incident or start remediation automation.
Automation Tasks
Automation Task Run Completed: A task run completed successfully and can start follow-up work.
Automation Task Run Failed: A task run failed and can create an incident or run cleanup.
Automation Task Approval Requested: A task is waiting for approval and can notify or escalate.
Automation Task Approval Approved: Approval was granted and follow-up tracking can run.
Automation Task Approval Rejected: Approval was rejected and can create a closure note or requester notification.
Event Data Variables
Event data is exposed as variables that can be used in action fields and Automation Task parameter values.
Use double-brace syntax in template-enabled fields, for example {{ subject_id }} or {{ application_id }}.
Common Variables
Common variables describe the event itself and are available across all listener types:
event_id event_type event_name event_created_utc tenant_id subject_type subject_id subject_name summary correlation_id initiated_by_user_id initiated_by_email initiated_by_display_name
Application Request Variables
application_request_id application_request_name application_request_state application_request_created_utc application_request_description requester_user_id requester_email requester_name contact_email contact_phone project_name department_owner environment business_justification technical_requirements intended_audience data_access_requirements compliance_notes expected_go_live_date_utc business_criticality requires_elevated_permissions elevated_permissions_justification topdesk_incident_id topdesk_incident_number
Application and Credential Variables
application_entity_id application_id application_object_id service_principal_id application_name application_state application_description secret_next_update_utc certificate_expires_at_utc credential_update_type credential_type credential_expires_at_utc credential_days_until_expiry error
Certificate Variables
certificate_template_id certificate_order_id certificate_primary_domain certificate_expires_at_utc certificate_thumbprint certificate_requested_at_utc error
Automation Task Variables
automation_task_id automation_task_name automation_task_run_id automation_task_run_status automation_task_run_started_utc automation_task_run_ended_utc automation_task_run_error automation_task_step_count automation_task_failed_step_count automation_task_approval_state approval_comment
TOPdesk Incident Action
The TOPdesk Incident action creates a TOPdesk incident directly from the event listener. Configure the integration and optional TOPdesk classification values on the listener.
TOPdesk Integration: The tenant integration used to create the incident.
Entry Type: Optional TOPdesk entry type id and display name.
Operator Group: Optional assignment group id and display name.
Category and Subcategory: Optional routing metadata sent to TOPdesk.
Automation Task Action
The Automation Task action starts a selected automation task when the event is received. The task selector is searchable, and the listener supports the same task input model used by schedules and linked schedules.
Automation Task: Search and select the task the listener should start.
Direct value: Store a static value for a task parameter.
Variable value: Map a task parameter from event data, such as {{ application_id }}, {{ certificate_primary_domain }}, or {{ automation_task_run_id }}.
Custom template: Combine fixed text and variables when the task parameter expects a formatted string.
Execution Architecture
Events are executed asynchronously. The application or service that creates the event does not run listener actions inline. Instead, it queues an event execution message and returns to its own work.
1. A platform feature creates an event, such as an application request, certificate renewal, or task run status change.
2. AZExecute queues an event execution message for the tenant.
3. AZExecute.Admin.Services.Events receives the message from the event queue.
4. The event service calls the Admin API event processing endpoint.
5. The Admin API resolves enabled listeners, applies tenant-scoped database access, and dispatches listener actions.
6. TOPdesk calls or Automation Task run creation happen from the server-side execution path and are recorded in listener history.
Common Patterns
Application Request to TOPdesk
Use Application Request Created with TOPdesk Incident to create an operator-facing ticket when users submit new application requests.
Include values such as {{ requester_email }}, {{ project_name }}, {{ environment }}, and {{ business_justification }}.
Certificate Renewal to Deployment Task
Use Certificate Renewal Completed with Automation Task to deploy the renewed certificate.
Map task parameters from {{ certificate_template_id }}, {{ certificate_primary_domain }}, {{ certificate_thumbprint }}, and {{ certificate_expires_at_utc }}.
Failed Run to Incident
Use Automation Task Run Failed with TOPdesk Incident to create a ticket that contains the failed task name, run id, failed step count, and error text.
Useful variables include {{ automation_task_name }}, {{ automation_task_run_id }}, {{ automation_task_failed_step_count }}, and {{ automation_task_run_error }}.
Task Chaining
Use Automation Task Run Completed with Automation Task to start follow-up work after a successful task. This is useful for post-deployment verification, cleanup, documentation updates, or notifying other systems.
Run History and Troubleshooting
Listener executions are tracked so operators can see whether an event matched a listener and whether the configured action succeeded.
Listener did not run: Confirm preview features are enabled, the listener is enabled, and the event type matches.
Message is queued but not processed: Check that AZExecute.Admin.Services.Events is deployed and running.
Admin API error: Check Admin API logs for the event id and tenant id. The worker calls the Admin API for actual processing.
TOPdesk incident was not created: Verify the selected TOPdesk integration, category ids, operator group id, and TOPdesk API permissions.
Automation task did not start: Verify the selected task still exists, required parameters are mapped, and any approval requirements are expected.
Variable is empty: Confirm that the selected event type emits that variable. Use the Event Data panel and exact {{ variable_name }} syntax.
Recommended Practices
Use clear listener names that include the trigger and target action, for example Certificate Renewal Failed - TOPdesk Incident.
Use execution order when multiple listeners should run in a predictable sequence for the same event.
Keep listener actions focused. Put complex multi-step work in an Automation Task and let the listener start that task.
Prefer event variables over hard-coded ids when values naturally come from the event payload.
Avoid accidental recursive loops when a task-completed listener starts another task that emits another task-completed event.
Document why each production listener exists in the description field so future operators understand the operational dependency.