Hooks and Webhooks

Rocky fires lifecycle events at key points during pipeline execution. You can attach shell scripts or HTTP webhooks to any event for notifications, gating, auditing, or custom integrations.

Lifecycle events

Events are organized into five phases:

Pipeline phase

Event	When	Use case
pipeline_start	Pipeline begins	Slack notification, deploy freeze gate
discover_complete	Source discovery finishes	Log connector/table counts
compile_complete	Compilation finishes	Validate types before execution
pipeline_complete	Pipeline succeeds	Success notification, metrics push
pipeline_error	Pipeline fails	PagerDuty alert, incident creation

Table phase

Event	When	Use case
before_materialize	Before table copy	Audit logging
after_materialize	After table copy	Publish to data catalog
materialize_error	Table copy fails	Per-table alerting

Model phase

Event	When	Use case
before_model_run	Before compiled model runs	Feature flag checks
after_model_run	After compiled model runs	Lineage metadata push
model_error	Model execution fails	Debug notification

Quality phase

Event	When	Use case
before_checks	Quality checks begin	Mute downstream alerts during expected check windows
check_result	A quality check completes	Per-check threshold alerting
after_checks	All checks finish	Aggregate summary to dashboards, gating on total pass rate
drift_detected	Schema drift found	Schema change notification
anomaly_detected	Row count anomaly	Data quality alert

State phase

Event	When	Use case
state_synced	State store synced	Backup confirmation

Budget phase

Event	When	Use case
budget_breach	Observed run cost or duration exceeds a limit declared in [budget]	Page oncall on overspend; gate downstream runs on on_breach = "error"

Adapter resilience phase

Event	When	Use case
circuit_breaker_tripped	Adapter circuit breaker moves Closed → Open after consecutive transient failures	Mute retries; notify oncall that a warehouse endpoint is unhealthy
circuit_breaker_recovered	Half-open trial request succeeds and the breaker closes	Clear the alert; record recovery latency

Circuit-breaker behaviour is configured per-adapter via [adapter.NAME.retry] — circuit_breaker_threshold sets the failure count that trips it, and circuit_breaker_recovery_timeout_secs enables timed auto-recovery through the half-open state.

Shell hooks

Shell hooks execute a command and pipe the event context as JSON to stdin:

[[hook.pipeline_complete]]
command = "bash scripts/slack-notify.sh"
timeout_ms = 5000
on_failure = "warn"

The script receives JSON like:

{
  "event": "pipeline_complete",
  "run_id": "run_20260402",
  "timestamp": "2026-04-02T14:30:00Z",
  "duration_ms": 45200,
  "metadata": {
    "tables_copied": "20",
    "tables_failed": "0"
  }
}

Failure handling

Mode	Behavior
abort	Stop the pipeline if the hook fails
warn	Log a warning and continue (default)
ignore	Silently continue

Use abort for gating hooks (deploy freeze, approval gates). Use warn or ignore for notifications.

Security: trust the command source

The command string is passed to sh -c verbatim. The event context is delivered to the script as JSON on stdin — it is not interpolated into the command line — so the runtime values Rocky exposes (run_id, event, etc.) cannot inject shell metacharacters into your command.

That said, never build a hook command by string-formatting untrusted input (a webhook payload, a Fivetran response, a value pulled from a row, anything you don’t fully control). Use only static commands or commands templated from values you control yourself. If you need to react to dynamic input, hand it off through the JSON context to a script you wrote, and let that script decide what to do with quoting / validation.

Webhooks

Webhooks send HTTP requests instead of running shell commands:

[hook.webhooks.pipeline_error]
url = "https://hooks.slack.com/services/T.../B.../xxx"
preset = "slack"
secret = "${WEBHOOK_SECRET}"

Built-in presets

Preset	Service	Body format
slack	Slack Incoming Webhook	Slack Block Kit JSON
pagerduty	PagerDuty Events API v2	PD event payload
datadog	Datadog Events API	DD event JSON
teams	Microsoft Teams Webhook	Adaptive Card JSON

Presets provide default body templates and headers. Override any field in your config.

HMAC signing

When secret is set, Rocky signs the request body with HMAC-SHA256:

X-Rocky-Signature: sha256=<hex-encoded digest>

The receiving service can verify the signature to ensure the request came from Rocky.

Body templates

Custom body templates use Mustache-style syntax:

body_template = """
{
  "text": "Pipeline {{event}}: {{metadata.tables_copied}} tables copied in {{duration_ms}}ms"
}
"""

Supported: {{field}}, {{metadata.key}}, {{#if field}}...{{/if}}.

Testing hooks

Validate your hook configuration without running a real pipeline:

# List all configured hooks
rocky hooks list

# Fire a test event
rocky hooks test pipeline_start

The test command sends a synthetic event context to verify scripts execute correctly.