Webhooks

Overview

Webhooks let external systems — CI/CD pipelines, monitoring tools, alerting systems — trigger playbook or workflow executions via a simple HTTP POST request. Each webhook has a unique URL and an optional shared secret for request verification.

Creating a webhook

Go to Webhooks → New webhook and configure:

• NameDescriptive label
• TargetA playbook or workflow to trigger
• InventoryTarget inventory (for playbook webhooks)
• Default extra varsBase variables merged with any vars sent in the request body
• SecretOptional HMAC-SHA256 shared secret for signature verification
• EnabledToggle to deactivate without deleting

After saving, you are shown the unique webhook URL. It is only displayed once — copy it immediately.

Triggering a webhook

curl -X POST https://your-instance.example.com/api/webhooks/trigger/abc123xyz \
  -H "Content-Type: application/json" \
  -d '{"extra_vars": {"deploy_branch": "main", "target_env": "production"}}'

The extra_vars field in the request body is merged with the webhook’s default extra vars. Request-body vars take precedence.

Signature verification

If a secret is configured, SculptOps verifies the X-Hub-Signature-256 header (compatible with GitHub’s webhook format) using HMAC-SHA256.

# Compute the signature (bash example)
PAYLOAD='{"extra_vars": {}}'
SECRET="your-webhook-secret"
SIG=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST https://your-instance/api/webhooks/trigger/abc123 \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=$SIG" \
  -d "$PAYLOAD"

Git push trigger

Point a GitHub or GitLab repository webhook directly at your SculptOps webhook URL — no additional configuration needed. When a push event is received, SculptOps automatically re-syncs the linked playbook from its Git repository before running the execution.

How it works

1. GitHub/GitLab sends a push event with a X-GitHub-Event: push or X-GitLab-Event: Push Hook header.
2. SculptOps extracts the branch name from the payload.
3. If a Git branch filter is set and the pushed branch doesn't match, the request is silently acknowledged and no execution is created.
4. If the branch matches (or no filter is set), the playbook is re-synced from Git, then the execution is queued.

Integration examples

GitHub Actions

- name: Trigger deploy via SculptOps
  run: |
    curl -X POST ${{ secrets.ANSIBLEGUI_WEBHOOK_URL }} \
      -H "Content-Type: application/json" \
      -H "X-Hub-Signature-256: sha256=$( \
          echo -n '${{ github.sha }}' | \
          openssl dgst -sha256 -hmac '${{ secrets.ANSIBLEGUI_WEBHOOK_SECRET }}' | \
          awk '{print $2}')" \
      -d '{"extra_vars": {"git_sha": "${{ github.sha }}"}}'

Alertmanager (on alert firing)

# alertmanager.yml
receivers:
  - name: ansible-remediation
    webhook_configs:
      - url: https://your-instance/api/webhooks/trigger/abc123
        send_resolved: false
        http_config:
          authorization:
            type: Bearer
            credentials: your-api-token

Grafana alert webhook

In Grafana, create a contact point of type Webhook and set the URL to your SculptOps webhook endpoint. No signature is required — use an IP allowlist or a Bearer token in the contact point headers instead.

Webhook execution history

Every webhook trigger is logged with the source IP, request headers (sanitized), payload, and the resulting execution ID. View the history under Webhooks → [webhook] → History.