Automation & Integrations•5 min read•Webhooks

Inbound Webhooks & CI/CD Triggers

Trigger automated playbooks from CI/CD pipelines and external services using token-authenticated inbound webhooks and the interactive developer workbench.

Manual execution from the dashboard works for ad-hoc maintenance, but modern delivery pipelines require automated triggers. When a pull request merges, a release tag is pushed, or a monitoring system flags a degraded node, automation must run without manual intervention.

CIEL provides Inbound Webhooks to connect external systems directly to certified automation workflows. External systems trigger playbooks over HTTP without requiring access to the web dashboard or administrative API credentials.

Inbound Webhook Triggers and Developer Workbench

1. Saved Runs as the Security Boundary

Inbound webhooks in CIEL never execute detached playbooks. Every webhook is bound directly to a Saved Run.

This binding acts as an immutable execution contract:

  • Target Playbook: The exact playbook file validated in Studio.
  • Inventory & Target Scope: The specific server group or host filter permitted for this trigger.
  • Execution Environment: The locked container image or host runtime.
  • Base Variable Stack: Workspace variable sets and default parameters.

External callers cannot alter the target inventory, switch playbooks, or pass arbitrary shell commands. Callers can only supply approved runtime variables (such as a Git commit hash or release version) that feed into the predetermined playbook.


2. Configuring an Inbound Webhook

To configure a webhook, navigate to Webhooks (/webhooks under RUNS & JOBS) and click + New Webhook. The drawer exposes five configuration fields:

1. Webhook Name

A descriptive operational title (for example, GitHub CD Release Deploy or Alertmanager Auto-Remediation). Names must be unique within the project.

2. Target Saved Run

Select an existing Saved Run from the dropdown. Once chosen, the live Execution Configuration Card displays the bound playbook, target inventory, host count, and execution mode (Native or Podman).

3. Required Dynamic Variables (Caller Contract)

Define mandatory variable keys that incoming JSON payloads must supply (such as release_tag or environment):

  • You can type custom variable names or click suggested keys directly from the selected Saved Run.
  • When an external caller triggers the webhook, CIEL checks the incoming payload before launching the runner. If any required variable is missing or empty, the request is immediately rejected with HTTP 422 Unprocessable Entity, preventing failed runs caused by incomplete parameters.

4. HMAC Secret Verification

Set a shared secret to authenticate incoming webhook signatures. You can enter a custom string or click Generate to create a secure random secret. CIEL validates incoming requests against standard signature headers:

  • X-Webhook-Secret: Custom header matching the shared secret.
  • X-Hub-Signature-256: GitHub HMAC-SHA256 signature verification.
  • X-Gitlab-Token: GitLab pipeline token validation.
  • Authorization: Bearer <secret>: Standard HTTP bearer token header.
  • Top-level JSON field: {"secret": "<secret>", ...} for simple callers.

If left empty, the webhook operates in token-only mode, authenticating requests purely through the unique endpoint token.

5. Active Toggle

Enable the webhook immediately upon saving or keep it paused for maintenance.


3. Developer Workbench & Trigger Modal

Clicking any webhook in the table opens the Webhook Trigger Dialog. This workbench provides everything developers need to test and integrate the endpoint into external tools:

Endpoint Bar & Credentials

  • HTTP Method & URL: Displays the complete URL containing your unique webhook token (/api/webhooks/trigger/<token>), with a one-click copy button.
  • Secret Management: Displays the masked secret with a reveal toggle and copy button.
  • Required Variables Chips: Visual indicators showing all mandatory keys enforced on this endpoint.

Integration Tabs

  1. cURL Command: Generates a ready-to-run Bash cURL command with your endpoint URL, authentication headers, and formatted JSON payload. A toggle lets you switch between:

    • Nested { extra_variables }: Standard Ansible runner structure.
    • Flat JSON: Simplified key-value pairs automatically parsed by CIEL.
  2. Live Playground: An in-browser testing console with syntax-highlighted JSON editing. You can load sample payloads (Standard Inbound Preset or SaaS Callback Preset), verify your variable keys, and click Send Trigger Request to run a test execution directly without leaving the dashboard.

  3. CI/CD Pipelines: Pre-built pipeline configurations for popular platforms:

    • GitHub Actions: Workflow step using repository secrets (CIEL_WEBHOOK_SECRET) and dynamic workflow context (github.sha, github.ref_name, github.actor).
    • GitLab CI: Pipeline stage script for .gitlab-ci.yml.
  4. SaaS Callback (Two-Way Webhooks): For systems that require asynchronous completion notices, you can include callback_url and optional callback_secret in the payload. When the Ansible playbook completes, CIEL sends an HTTP POST back to your callback URL with the final job status, duration, and execution metadata.


4. Pipeline Integration Examples

GitHub Actions

Add the following step to your .github/workflows/deploy.yml workflow:

yaml
- name: Trigger CIEL Deployment
  run: |
    curl -f -X POST "https://ciel.your-company.com/api/webhooks/trigger/${{ secrets.CIEL_WEBHOOK_TOKEN }}" \
      -H "Content-Type: application/json" \
      -H "X-Webhook-Secret: ${{ secrets.CIEL_WEBHOOK_SECRET }}" \
      -d '{
        "extra_variables": {
          "release_tag": "${{ github.ref_name }}",
          "commit_sha": "${{ github.sha }}",
          "deployed_by": "${{ github.actor }}"
        }
      }'

GitLab CI

Add the following job to your .gitlab-ci.yml pipeline:

yaml
deploy_production:
  stage: deploy
  only:
    - main
  script:
    - |
      curl -f -X POST "https://ciel.your-company.com/api/webhooks/trigger/$CIEL_WEBHOOK_TOKEN" \
        -H "Content-Type: application/json" \
        -H "X-Gitlab-Token: $CIEL_WEBHOOK_SECRET" \
        -d "{
          \"extra_variables\": {
            \"commit_sha\": \"$CI_COMMIT_SHA\",
            \"branch\": \"$CI_COMMIT_REF_NAME\",
            \"deployed_by\": \"$GITLAB_USER_LOGIN\"
          }
        }"

5. Security Controls & Operational Management

Because webhooks expose automation triggers to network services, CIEL applies multiple layers of operational safety:

  • Token Regeneration: If a webhook URL or token is accidentally committed to a public repository, click Regenerate Token in the webhook context menu. CIEL immediately generates a new token and revokes the old URL without modifying your Saved Run or required variables contract.
  • Creator RBAC Validation: When a webhook triggers, the background worker verifies that the user who created the webhook is active and retains owner, maintainer, or operator permissions in the project. If the creator is deactivated, triggers return HTTP 403 Forbidden.
  • Level 22 Variable Precedence: Variables passed via webhook payloads take precedence as extra variables (Ansible Level 22). They override default inventory and playbook values for that single run without permanently mutating workspace state.
  • Execution Audit Trail: Every incoming trigger records caller IP, timestamp, passed parameters, and links directly to real-time ANSI logs in the Jobs visualizer.

6. External References

For upstream specifications on webhook security and CI/CD automation: