Add an Event-Driven Ansible trigger

An Event-Driven Ansible (EDA) trigger starts a workflow using an action defined in an Event-Driven Ansible controller instance connected to your Ansible Automation Platform deployment.

Before you begin

  • You have access to the workflow builder.
  • The workflow is in an editable state.
  • An Event-Driven Ansible controller instance is connected to your Ansible Automation Platform deployment.
  • Event sources are configured in your Event-Driven Ansible controller instance. For more information about configuring event sources, see the Event-Driven Ansible documentation in the Ansible Automation Platform documentation set.

About this task

Use this trigger type for event-driven automation where Event-Driven Ansible detects events in your infrastructure and routes them to automation orchestrator for analysis and remediation. For example, Event-Driven Ansible can detect a log pattern indicating a CPU spike and send the event data to a workflow. A task agent step in the workflow analyzes the data and identifies the appropriate Ansible Automation Platform job template to resolve the issue.

The Event-Driven Ansible trigger uses the webhook mechanism. Automation orchestrator generates a webhook endpoint URL, and you configure a rulebook activation in your Event-Driven Ansible controller to send events to that endpoint.

If you are creating a new workflow, select the Event-Driven Ansible trigger option from the Add step panel and begin this procedure at step 3.

Note:
Event-Driven Ansible trigger endpoints are unauthenticated by default. If you do not configure an authorized service account, any system that can reach the endpoint URL can trigger the workflow. To secure the endpoint, select at least one authorized service account during trigger configuration.

Procedure

  1. Navigate to the Workflows page and select the workflow you want to modify.
  2. Click Add step > Triggers > Event-Driven Ansible trigger.
  3. Review the Webhook path field, which is pre-populated with a unique, auto-generated path.

    You can modify this path if needed. This path becomes part of the final generated URL.

  4. Note that the HTTP method field displays POST.

    The Event-Driven Ansible trigger accepts POST requests only. This value cannot be changed.

  5. From the field labeled URL, copy the generated webhook endpoint URL.

    You need this URL to configure the rulebook activation in the webhook settings of your Event-Driven Ansible controller.

    Important:

    Event-Driven Ansible triggers use a different URL path than standard webhooks. The URL follows the pattern https://orchestrator-host/api/v1/webhooks/eda/webhook-path. Use the exact URL shown in the URL field when configuring your rulebook activation.

  6. In the Authorized service accounts field, select one or more service accounts that can call this endpoint.

    You can create a new service account inline if one does not exist. The rulebook activation must authenticate with a Bearer token obtained from one of these service accounts.

    Note:

    If you do not select a service account, the Event-Driven Ansible trigger endpoint accepts unauthenticated requests from any source that can reach the automation orchestrator API. Configure at least one authorized service account to restrict access to the endpoint.

  7. Optional: In the Request body field, define a schema to validate incoming event payloads.

    Use Simple mode to define flat key-value fields, or Advanced mode to provide a full JSON schema. If the incoming payload does not match the schema, the trigger rejects the request.

  8. Click Create or Update to save the step and add it to the canvas.
  9. Click Save in the toolbar to save the workflow.
  10. In your Event-Driven Ansible controller, create or update a rulebook activation.

    Configure the activation to send matching events to the webhook endpoint URL. For a complete example with a ready-to-use playbook and rulebook, see Event-Driven Ansible trigger integration reference.

Results

  1. Publish the workflow to activate the Event-Driven Ansible trigger.
  2. Trigger a test event in the event source that your rulebook activation monitors.
  3. Navigate to the workflow's run history to confirm that the event triggered a new workflow run.

Event-Driven Ansible trigger integration reference

Event-Driven Ansible cannot call automation orchestrator directly. Instead, configure a rulebook activation that delegates the event to a job template. The job template playbook authenticates and sends the payload to the trigger endpoint.

The integration flow is:

  1. An event source sends an event to Event-Driven Ansible.
  2. A rulebook activation matches the event and runs a job template action.
  3. The job template runs a playbook that authenticates with automation orchestrator and sends a POST request with the event payload to the Event-Driven Ansible trigger endpoint.
  4. Automation orchestrator starts the workflow.

Example playbook

The following playbook obtains an OAuth 2.0 token using service account client credentials. It then sends the event payload to the automation orchestrator Event-Driven Ansible trigger endpoint. Use this playbook as the job template that your rulebook activation calls.

Replace webhook_base_url, webhook_client_id, and webhook_client_secret with values from your environment. In production, store these values in a custom credential type. Attach the credential type to the job template rather than passing values as extra variables.

---
- name: Trigger EDA webhook
  hosts: localhost
  connection: local
  gather_facts: false

  vars:
    webhook_base_url: ""
    webhook_path: ""
    webhook_client_id: ""
    webhook_client_secret: ""
    event_payload: {}

  tasks:
    - name: Obtain OAuth token
      ansible.builtin.uri:
        url: "{{ webhook_base_url }}/api/v1/auth/token"
        method: POST
        body_format: form-urlencoded
        body:
          grant_type: client_credentials
          client_id: "{{ webhook_client_id }}"
          client_secret: "{{ webhook_client_secret }}"
        status_code: 200
      register: token_response

    - name: Post event payload to Event-Driven Ansible trigger endpoint
      ansible.builtin.uri:
        url: "{{ webhook_base_url }}/api/v1/webhooks/eda/{{ webhook_path }}"
        method: POST
        body_format: json
        headers:
          Authorization: "Bearer {{ token_response.json.access_token }}"
          Content-Type: application/json
        body: "{{ event_payload }}"
        status_code: 202
      register: webhook_response

    - name: Display execution ID
      ansible.builtin.debug:
        msg: "Workflow execution started: {{ webhook_response.json.execution_id }}"

The two HTTP requests are:

  • Obtain OAuth 2.0 token: Sends a client_credentials grant request to the automation orchestrator token endpoint. The webhook_client_id and webhook_client_secret values come from a service account that you authorized on the Event-Driven Ansible trigger step in the workflow builder.
  • Post event payload: Sends the event data to the Event-Driven Ansible trigger endpoint using the Bearer token. The endpoint returns a 202 Accepted response with the workflow run ID.

Example rulebook

The following rulebook listens for incoming events and forwards the entire event payload to a job template. The job template runs the playbook shown above.

---
- name: Forward events to the workflow trigger
  hosts: all
  sources:
    - ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000

  rules:
    - name: Forward all events to the workflow trigger
      condition: event.payload is defined
      action:
        run_job_template:
          name: "Trigger EDA Webhook"
          organization: Default
          job_args:
            extra_vars:
              webhook_path: "{{ webhook_path }}"
              event_payload: "{{ event.payload }}"

The rulebook forwards any event with a defined payload field. Set the webhook_path variable as an extra variable on the rulebook activation in your Event-Driven Ansible controller. The event_payload variable passes the entire event payload to the job template without filtering specific fields.

Job template configuration

To connect the playbook and rulebook, create the following resources in automation controller:

  • Project: A project that contains the playbook.
  • Custom credential type: A credential type that supplies webhook_base_url, webhook_client_id, and webhook_client_secret as extra variables to the playbook.
  • Job template: A job template named Trigger EDA Webhook (or the name you specified in the rulebook run_job_template action) that uses the project and credential.
  • Rulebook activation: A rulebook activation in your Event-Driven Ansible controller that uses the rulebook. Set webhook_path as an extra variable on the activation, using the webhook path from the Event-Driven Ansible trigger step in automation orchestrator.