Hooks Reference

Hooks and Webhooks

Run shell commands at sync lifecycle and object completion points. Send one JSON summary per run to each configured webhook.

Lifecycle hooks

Lifecycle hooks wrap the sync command. The start hook is blocking. Success, error, and finally hooks are best-effort.

godwit sync \
  --source ./data \
  --destination ./backup \
  --on-start "./hooks/check.sh" \
  --on-success "./hooks/complete.sh" \
  --on-error "./hooks/failed.sh" \
  --on-finally "./hooks/cleanup.sh"

Flag	Config key	Behavior
`--on-start`	`hooks.on_start`	Runs before sync. A non-zero exit stops the run.
`--on-success`	`hooks.on_success`	Runs after sync returns without an error. A successful plan-only run reports planned status.
`--on-error`	`hooks.on_error`	Runs after sync returns an error. Hook failure does not replace the sync error.
`--on-finally`	`hooks.on_finally`	Runs after the sync operation returns success or error. It does not run when --on-start aborts before sync. Hook failure does not change the process exit status.

Godwit Sync invokes command hooks through sh on Unix and cmd on Windows. Hook output is written to standard error.

Lifecycle environment

Command hooks receive run metadata through GODWIT_* environment variables. Statistics are set for success, error, and finally phases.

Variable	Value
`GODWIT_PHASE`	start, success, error, finally, or object
`GODWIT_RUN_ID`	Current run identifier
`GODWIT_STATUS`	Empty at start; completed, failed, or planned after the operation
`GODWIT_SOURCE`	Source URI
`GODWIT_DESTINATION`	Destination URI
`GODWIT_OBJECTS_TOTAL`	Objects in the run snapshot
`GODWIT_OBJECTS_TRANSFERRED`	Successfully transferred objects
`GODWIT_OBJECTS_SKIPPED`	Skipped objects
`GODWIT_OBJECTS_FAILED`	Failed objects
`GODWIT_BYTES_TRANSFERRED`	Transferred bytes excluding failed bytes
`GODWIT_DURATION_SECONDS`	Elapsed seconds as a decimal value
`GODWIT_ERROR`	Sync error text on the error phase

Per-object hooks

--on-key fires after completed and failed transfer tasks. Skipped and excluded objects do not fire this hook.

godwit sync \
  --source ./data \
  --destination ./backup \
  --on-key "./hooks/index-object.sh"

Variable	Value
`GODWIT_KEY`	Object key
`GODWIT_SIZE`	Object size in bytes
`GODWIT_VERSION_ID`	S3 version ID when the source task carries one; otherwise unset
`GODWIT_STATUS`	completed or failed
`GODWIT_ERROR`	Object error text for failed tasks; otherwise unset

Per-object commands run synchronously in transfer worker goroutines. Slow commands reduce throughput. Command failures are best-effort and do not fail the transfer.

Webhook notifications

Repeat --notify to POST the terminal run summary to multiple HTTP endpoints. The payload includes a Slack-compatible text field and structured fields.

godwit sync \
  --source ./data \
  --destination ./backup \
  --notify https://hooks.example.com/godwit \
  --notify https://monitoring.example.com/runs

Payload

{
  "text": "Godwit run `daily-backup` completed: 142 objects (5.0 GiB) transferred in 47s, 0 failures",
  "run_id": "daily-backup",
  "status": "completed",
  "source": "./data",
  "destination": "./backup",
  "objects_total": 142,
  "objects_transferred": 142,
  "objects_skipped": 0,
  "objects_failed": 0,
  "bytes_transferred": 5368709120,
  "duration_seconds": 47.3,
  "finished_at": "2026-07-22T14:22:01Z"
}

Property	Behavior
Dispatch	Success or error terminal phase only. Start, finally, and object phases do not send webhooks. A start-hook abort sends no webhook.
Timeout	10 seconds per HTTP request.
Retry	One retry after 2 seconds for transport errors and HTTP 5xx. HTTP 4xx is not retried.
Multiple URLs	URLs are processed sequentially.
Delivery failure	Logged as hook_failed. Delivery failure does not change the sync exit status.

Setup guides

Slack

Post a run summary to a Slack channel with an incoming webhook.

Set up Slack notifications

Discord

Post a run summary to a Discord channel using its Slack-compatible webhook endpoint.

Set up Discord notifications

YAML configuration

The hooks section maps directly to sync hook flags.

source:
  url: ./data
destination:
  url: ./backup
hooks:
  on_start: ./hooks/check.sh
  on_success: ./hooks/complete.sh
  on_error: ./hooks/failed.sh
  on_finally: ./hooks/cleanup.sh
  on_key: ./hooks/index-object.sh
  notify:
    - https://hooks.example.com/godwit

An explicitly set CLI hook flag replaces the corresponding config value. An explicitly set --notify list replaces hooks.notify.