# Notifications

Route run and schedule outcomes to email or a Slack webhook, so a failure reaches someone instead of waiting to be noticed.

Source: https://opafra.com/docs/governance/notifications

---

Opafra records every run outcome in the interface. Notifications push those outcomes to
email or a webhook, so a failed overnight run reaches a person rather than waiting to be
found.

## Before you begin

Notification settings are per user, not per organisation. Each person configures their
own, so there is no role requirement beyond having an account.

## 1. Choose which categories to receive

Open **Settings**, then **Notifications**. Two categories:

```text
Execution alerts    Plan executions complete or fail
Scheduler alerts    Scheduled task failures
```

Both are on unless you turn them off. Turning a category off stops it reaching your
external channels entirely.

## 2. Turn on email

Switch on **Email me notifications**. Messages go to the address on your account.

## 3. Add a webhook

Paste an incoming webhook URL. A Slack incoming webhook is the common case:

```text
https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXX
```

The webhook fires whenever a URL is set. There is no separate switch for it, so clearing
the field is how you turn it off.

## Verify it worked

Use **Test** beside the webhook field. A test message arrives in the channel within a few
seconds:

```text title="slack"
Opafra
Test notification
Your webhook is configured correctly.
```

Then confirm the real path end to end. Run a plan that fails on purpose, such as a step
targeting a host that does not exist, and check the message arrives naming the plan:

```text title="slack"
Opafra
Plan failed: Patch nginx
Step 2 failed on web-02. View the run.
```

The bell in the header shows the same notification regardless of your external settings.
Those settings control what leaves Opafra, not what is recorded.

## What sends a notification

Runs and schedules only:

| Event | Category |
|---|---|
| A run completes | Execution alerts |
| A run fails | Execution alerts |
| A run starts | Execution alerts |
| A scheduled task fails | Scheduler alerts |

> **Important**
>
> **An approval waiting for you does not send a notification.** A gated run pauses and
> appears in the approvals inbox, and nothing pushes that anywhere. If your team relies on
> gates, someone has to watch the inbox, or the run waits until they do. See
> [approval gates](/docs/running/approval-gates).

Nothing else notifies: not a member change, not a secret provider disconnecting, not a git
sync failure, and **not an [alert](/docs/inventory/alerts) firing**. Those are recorded and
visible in the interface, and you find them by looking.

## Delivery is best effort

A notification that cannot be delivered is logged and dropped. It does not retry and it
does not fail the run that produced it, on the same reasoning as the audit write: a
messaging problem should not become an outage.

So treat notifications as a convenience rather than a guarantee. The run record is the
thing that is always correct.

## Next steps

- [Scheduling](/docs/running/scheduling) for the runs most worth being told about
- [Audit log](/docs/governance/audit-log) for what is recorded rather than pushed