# Notifications Bridge

The notifications bridge forwards community events out to **Slack**, **Microsoft Teams**, or **Discord** using an incoming webhook. Manage it at **Admin → Bridge** (`/admin/bridge`). It requires the Administrator role.

Delivery is one-way: events leave your community and arrive in the outside channel. Nothing comes back in.

## Set up a target

1. Go to **Admin → Bridge** and start a new target.
2. Choose the service — Slack, Teams, or Discord.
3. Give the target a display name. This is what you will see in the target list and in the footer of each delivered message.
4. Paste the webhook URL. It must begin with `https://` and must resolve to a public address; the bridge refuses private and internal addresses, and re-checks the address again at delivery time.
5. Tick at least one event. Saving is refused if none are selected.
6. Optionally set a forum scope (see below).
7. Click **Create target**.
8. Once the target is saved, use **Test** on its row to send a sample delivery and confirm it arrives. Test is only available after saving — there is no test before the target exists.

For Slack, the destination channel is fixed by Slack when you create the incoming webhook, not by anything you enter here.

## Events you can forward

The event picker lists each event by its identifier. The full set is:

| Event | Fires when |
|---|---|
| `forum.thread.created` | A member starts a thread |
| `forum.reply.posted` | A member replies to a thread |
| `mention.received` | A member is mentioned |
| `announcement.posted` | An announcement is published |
| `moderation.flag.raised` | A member flags content |
| `moderation.action.taken` | A moderator acts on content |
| `user.registered` | A new member joins |
| `user.first_post` | A new member posts for the first time |
| `file.uploaded` | A file is uploaded |
| `marketplace.listing.created` | A marketplace listing is created |
| `event.created` | A community event is created |

## Forum scope

Scope narrows a target to specific forums. Only the forum-tied events — `forum.thread.created` and `forum.reply.posted` — honour it. Tenant-level events such as `announcement.posted` and the moderation events always fire regardless of scope.

## What a delivered message contains

For a new thread, the message carries the forum name in its heading, then the thread title, the member who posted it, a preview of the opening post of roughly 280 characters, and an **Open** button linking straight to the thread. A reply carries the replier, the thread it belongs to, a preview of the reply, and a link anchored to that post.

Three cases deliberately send less:

- **Anonymous posts** report the author as "Anonymous". The real username is never sent, matching what readers see on the site.
- **Deleted or hidden posts** send no body. A post removed by a moderator or by automatic moderation between posting and delivery will not have its text forwarded.
- **Scheduled threads** that have not reached their publish time send no content, so nothing reaches the outside channel before it is visible in the community.

In each of those cases the message falls back to a short reference such as `thread #155 in #announcements` rather than being dropped.

## Delivery, retries, and target health

- Each event is attempted up to three times, with a delay of 0, then 60, then 300 seconds.
- After five consecutive failures a target is marked **broken** and stops receiving deliveries until you fix and re-enable it. This protects the queue from a revoked webhook.
- Deliveries are capped at 60 per minute per target.
- The delivery log keeps 30 days of history, and at most 1,000 rows per target.

A webhook that has been revoked in Slack typically answers with HTTP 200 and an error word rather than a failure code. The bridge treats anything other than a success acknowledgement as a failed delivery, so a revoked webhook still trips the health break rather than silently discarding events.

## Managing targets

- **Edit** — change the service, webhook URL, display name, events, or scope.
- **Test** — send a sample delivery to confirm the target works.
- **Delete** — remove the target.

Disabling a target stops delivery without deleting its history.

## How your data is handled

The webhook URL is encrypted at rest with AES-256-GCM. The admin screen shows only a short fingerprint of it, never the URL itself, so an admin can tell two targets apart without the secret being redisplayed.

The delivery log records what was sent and when, but stores only a short reference to the source — an identifier such as `thread:155` — never the post text. Message content is read from the live post at the moment of delivery, which is why an edited, deleted, or hidden post is reflected correctly instead of being sent from a stale copy.