Webhooks и уведомления

В v1 webhooks поддерживаются на двух уровнях:

• job-level
• task-level

Поддерживаемые события

Job-level:

• on_started
• on_success
• on_failure
• on_partial_success
• on_cancelled
• on_timeout
• on_finished

Task-level:

• on_started
• on_success
• on_failure
• on_skipped
• on_cancelled
• on_timeout
• on_finished

Аутентификация webhook

• none
• bearer — ровно один из token_env | token_path | token_vault
• basic — username + ровно один из password_env | password_path | password_vault
• header — header_name + ровно один из header_value_env | header_value_path | header_value_vault

Семантику *_vault см. в job-format-v1.md (KV v2 на Vault агента).

Retry policy

Поддерживаются:

• fixed
• exponential

Управление retry по типам ошибок:

• 4xx/5xx
• timeout
• network error

Гарантии по backup-статусу

Ошибка webhook не должна менять результат backup run/task.

Delivery статус и попытки сохраняются в metadata store (notification_events), что дает полный аудит доставки.

Payload policy (0.17-fix.50)

В webhook конфигурации можно указать policy:

• include_job_snapshot (default: false)
• include_manifest (default: false)
• include_labels (default: true)
• include_paths (default: false)

Независимо от этих флагов, payload проходит через redaction layer: секреты и secret-like поля маскируются, а пути/object keys по умолчанию не включаются.

Семантика флагов:

• include_job_snapshot: false (дефолт) — в тело webhook не включается executed_job_snapshot (полный sanitized job).
• include_manifest: false (дефолт) — не включается блок манифеста / backup_manifest в payload. true осмысленно в первую очередь для task-level webhook, когда известен конкретный backup_id. Для job-level webhook с несколькими задачами прикрепление «полного» манифеста job не гарантируется и часть сценариев отложена (несколько артефактов на run).
• include_paths — даже при true значения проходят через redaction (basename vs full — см. конфиг агента и docs/reference/job-format-v1.md).

Пример минимального DTO (после 0.17-fix.50; набор полей может расширяться):

{
  "event": "task.finished",
  "job_uid": "job_01J…",
  "job_id": "mysql-prod",
  "run_id": "run_01J…",
  "task_id": "mysql-main",
  "status": "success",
  "warnings_count": 0,
  "last_warning_code": null,
  "request_id": "req_01J…",
  "correlation_id": "corr_01J…"
}

Примеры machine-readable предупреждений/кодов, которые могут появляться в потоке событий или логах доставки (не исчерпывающий список): WEBHOOK_DELIVERY_FAILED, RETENTION_PARTIAL_FAILURE — детали в docs/reference/error-codes.md и notification_events.

• Пайплайн backup не считает webhook «успешным по умолчанию»: ошибки доставки остаются в notification_events и в логах агента.
• Оператор должен мониторить notification_events / метрики iobackup_notifications_*, иначе «тихий» сбой доставки возможен только в смысле отсутствия внешнего алерта — не из-за подавления ошибки в коде backup.