# 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`)
 * `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).

Available notification services are 

 * Discord webhook
 * Gotify 
 * Shoutrrr destinations https://containrrr.dev/shoutrrr/v0.8/ 
 * Command (e.g. execute a shell script)

## 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                                                      |

## 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 }}`.
 * `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`
 * `.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 }}
```