# Hook Details

## Hook Types

Backrest supports hooks in response to operation lifecycle events e.g. in response to the commands it runs on your behalf.

Available event types are

- `CONDITION_ANY_ERROR` any operation has failed.
- `CONDITION_SNAPSHOT_START` the start of a backup operation (e.g. corresponds to a call to `restic backup`, supports error behavior)
- `CONDITION_SNAPSHOT_END` the end of a backup operation (e.g. corresponds to `restic backup` completing). Note that Snapshot End will still be called if a backup failed.
- `CONDITION_SNAPSHOT_ERROR` an error occurred during a backup operation (e.g. `restic backup` returned a non-zero exit code OR invalid output).
- `CONDITION_SNAPSHOT_WARNING` a warning occurred during a backup operation (e.g. a file was partially read).
- `CONDITION_SNAPSHOT_SUCCESS` a backup operation completed successfully.
- Prune hooks:
  - `CONDITION_PRUNE_START` the start of a prune operation (e.g. corresponds to a call to `restic prune`, supports error behavior)
  - `CONDITION_PRUNE_SUCCESS` the end of a prune operation e.g. `restic prune` completed successfully.
  - `CONDITION_PRUNE_ERROR` an error occurred during a prune operation (e.g. `restic prune` returned a non-zero exit code).
- Check hooks:
  - `CONDITION_CHECK_START` the start of a check operation (e.g. corresponds to a call to `restic check`, supports error behavior)
  - `CONDITION_CHECK_SUCCESS` the end of a check operation e.g. `restic check` completed successfully.
  - `CONDITION_CHECK_ERROR` an error occurred during a check operation (e.g. `restic check` returned a non-zero exit code).

## Notification Services

| Service  | Docs                                                                      |
| -------- | ------------------------------------------------------------------------- |
| Discord  | https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks |
| Slack    | https://api.slack.com/messaging/webhooks                                  |
| Gotify   | https://github.com/gotify/server                                          |
| Shoutrrr | https://containrrr.dev/shoutrrr/v0.8/                                     |
| Command  | See command cookbook                                                      |


## Error Behavior

Some hooks can specify an error behavior (today this is only command hooks). This determines what happens when the hook generates an error.

The available error behaviors are:

- `ON_ERROR_IGNORE` - ignore the error and continue running hooks and the operation.
- `ON_ERROR_CANCEL` - cancel the operation and do not run any further hooks. The operation is marked as cancelled.
- `ON_ERROR_FATAL` - cancel the operation and do not run any further hooks. The operation is marked as failed and error handler hooks may be triggered.

## Using Templates

Most hooks will generate either a notification or execute a script. The script / notification is typically formatted as a Go template. The https://pkg.go.dev/text/template docs provide a very technical overview of Go template capabilities. See below for info about the available variables and for some examples.

Variables

- `Event:v1.Hook_Condition` - the event that triggered the backup. This is an enum. Values are one of: Hook_CONDITION_SNAPSHOT_START, Hook_CONDITION_SNAPSHOT_END, Hook_CONDITION_ANY_ERROR, Hook_CONDITION_SNAPSHOT_ERROR .
- `Task:string` - the name of the task that triggered the hook (e.g. `one time backup for plan "foo"`
- `Repo:v1.Repo` - the repo that triggered the backup. This is a struct. Access the name as `{{ .Repo.Id }}`
- `Plan:v1.Plan` - the plan that triggered the backup. This is a struct. Access the name as `{{ .Plan.Id }}`
- `SnapshotId:string` - the snapshot ID associated with the operation or empty string if none is associated.
- `SnapshotStats:restic.BackupProgressEntry` - summary of the current backup operation. This is a struct. See examples below for details.
- `CurTime:time.Time` - the current time. This is a struct. Format as `{{ .FormatTime .CurTime }}`.
- `Duration:time.Duration` - the duration of the triggering operation. Format as `{{ .FormatDuration .Duration }}`.
- `Error:string` - the error message if an error occurred, or empty string if successful.

Functions

- `.Summary` - prints a default summary of the current event.
- `.FormatTime <time>` - formats a time.Time object e.g. as `2024-02-08T03:00:37Z`.
- `.FormatDuration <duration>` - formats a time.Duration object e.g. as `1h2m3s`.
- `.FormatSizeBytes <int>` - formats a number as a size in bytes (e.g. 5MB, 10GB, 30TB, etc...)
- `.ShellEscape <string>` - escapes a string to safely be used in most shell environments. Should not be relied upon as secure for arbitrary input.
- `.JsonMarshal <any>` - attempts to marshall any value as JSON. Can also be used with literals e.g. to quote a string with escapes i.e. `hello"world` -becomes `"hello\"world"`.

## Summary Template

The current implementation of `.Summary`:

```
Task: "{{ .Task }}" at {{ .FormatTime .CurTime }}
Event: {{ .EventName .Event }}
Repo: {{ .Repo.Id }}
Plan: {{ .Plan.Id }}
Snapshot: {{ .SnapshotId }}
{{ if .Error -}}
Failed to create snapshot: {{ .Error }}
{{ else -}}
{{ if .SnapshotStats -}}

Overview:
- Data added: {{ .FormatSizeBytes .SnapshotStats.DataAdded }}
- Total files processed: {{ .SnapshotStats.TotalFilesProcessed }}
- Total bytes processed: {{ .FormatSizeBytes .SnapshotStats.TotalBytesProcessed }}

Backup Statistics:
- Files new: {{ .SnapshotStats.FilesNew }}
- Files changed: {{ .SnapshotStats.FilesChanged }}
- Files unmodified: {{ .SnapshotStats.FilesUnmodified }}
- Dirs new: {{ .SnapshotStats.DirsNew }}
- Dirs changed: {{ .SnapshotStats.DirsChanged }}
- Dirs unmodified: {{ .SnapshotStats.DirsUnmodified }}
- Data blobs: {{ .SnapshotStats.DataBlobs }}
- Tree blobs: {{ .SnapshotStats.TreeBlobs }}
- Total duration: {{ .SnapshotStats.TotalDuration }}s
{{ end }}
{{ end }}
```