A webhook is a user-defined HTTP callback, performed as an HTTP POST request, which allows applications to communicate and share information with each other. Most often, webhooks are used to inform applications about events. The message sent by the POST request is usually formatted as JSON or XML content or as form data that the application can interpret. Webhook calls are usually authenticated to ensure that unauthorized requests are rejected.

Previously you learned that Event-Driven Ansible can react to incoming webhook events by using the ansible.eda.webhook event source plug-in. If the webhook events come from a Git repository, triggered by operations such as new commits being added to a particular branch, then Event-Driven Ansible controller can communicate with automation controller to perform specific tasks.

For example, a new commit to a Git repository could cause Event-Driven Ansible controller to trigger a workflow template in automation controller. The workflow template might update a related project and then launch a job template that uses that project.

The following diagram shows a continuous integration workflow using webhooks and Event-Driven Ansible.

Figure 3.1: Continuous integration workflow using webhooks and Event-Driven Ansible

You can create the following Ansible Rulebook as a starting point to test webhooks sent from a Git repository:

---
- name: Capture events posted from Git server
  hosts: all
  sources:
    - name: Match events posted to port 5000
      ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000

  rules:
    - name: Debug if the webhook has a payload
      condition: event.payload is defined
      action:
        debug:

On receiving an event payload, the single rule prints the event data by using the debug action.

Before Event-Driven Ansible controller can react to Git webhook events, you must configure your Git repository to send webhooks.

Your Git repository server can be any implementation that can send webhooks, such as GitHub, GitLab, Gitea, and so on. In this course, GitLab is used as the Git repository server.

After testing a webhook, you can obtain values from the event and use this information to create rules in rulebooks.

Figure 3.5:

Headers example for a webhook push event

You can use event header information to create rules that match a specific event type.

---
- name: Capture events posted from Git server
  hosts: all
  sources:
    - name: Match events posted to port 5000
      ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000
      filters:
        - ansible.eda.dashes_to_underscores:

The following examples assume that you specified the ansible.eda.dashes_to_underscores filter for the event source plug-in, so that the hyphens in the displayed header output are converted to underscores in the conditions.

  rules:
    - name: Get push event details
      condition: event.meta.headers.X_Gitlab_Event == "Push Hook"

  rules:
    - name: Get merge event details
      condition: event.meta.headers.X_Gitlab_Event == "Merge Request Hook"

With these new conditions, you can run your rulebook and test the event again, analyze the View details output, and increase the number of conditions for the rulebook rules.

By refining your rule conditions, you can ensure that your rule only applies to the events that are important to you.

The following rulebook runs the Development deploy job template in automation controller in response to push events from the devel branch of your gitops_app project in GitLab:

---
- name: Capture events posted from Git server
  hosts: all
  sources:
    - name: Match events posted to port 5000
      ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000
      filters:
        - ansible.eda.dashes_to_underscores:

  rules:
    - name: Respond to push event
      condition: >
        event.payload.repository.name == "gitops_app"
        and event.meta.headers.X_Gitlab_Event == "Push Hook"
        and event.payload.ref is search("devel")
      action:
        run_job_template:
          name: Development deploy
          organization: Default