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.
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
-
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.
- Nested
-
Live Playground: An in-browser testing console with syntax-highlighted JSON editing. You can load sample payloads (
Standard Inbound PresetorSaaS Callback Preset), verify your variable keys, and click Send Trigger Request to run a test execution directly without leaving the dashboard. -
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.
- GitHub Actions: Workflow step using repository secrets (
-
SaaS Callback (Two-Way Webhooks): For systems that require asynchronous completion notices, you can include
callback_urland optionalcallback_secretin 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:
- 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:
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, oroperatorpermissions in the project. If the creator is deactivated, triggers returnHTTP 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:
- GitHub Webhook Security Guidelines: Best practices for validating HMAC-SHA256 signatures via
X-Hub-Signature-256. - GitLab Webhook Token Verification: Authenticating incoming requests using the
X-Gitlab-Tokenheader. - Ansible Variable Precedence: Understanding how extra variables (
-e) override defaults during runtime execution.