# Channels

Channels decide where the alerts of a project go: email addresses, your own webhook endpoint, Slack, Discord or Microsoft Teams. A project can have several channels, each with its own filters and delivery. Open the project, then **Channels** and **Add channel**.

A channel belongs to one project and only gets the alerts of that project: its software, its watches, its sites and its CVE rules. To get the alerts of several projects in one place, see [Several projects in one place](#projects).

## Kinds of channels

| Channel         | How you connect it                            | Plans      |
| --------------- | --------------------------------------------- | ---------- |
| Email           | Add addresses, each one confirms first        | Paid plans |
| Webhook         | Your own HTTPS URL, verified with a challenge | All        |
| Slack           | Choose a channel on the Slack consent screen  | All        |
| Discord         | Paste the URL of a Discord webhook            | All        |
| Microsoft Teams | Paste the URL of a Teams workflow             | All        |

Every channel gets the same alerts, except Discord on the Free plan, which only gets CVE rule alerts. Email and chat apps get a readable message, webhooks the signed JSON described in [Events and payloads](https://ladon.hackindex.io/docs/events.md).

## Email

Email channels are part of the paid plans. Add one or more email addresses. Every recipient first gets a confirmation email with a link that is valid for 7 days, and only receives alerts after confirming. Every alert email has an unsubscribe link that works with one click, also from mail clients that support one-click unsubscribe.

Alert emails use the language of the channel, see [Language](#language).

## Webhooks

Ladon sends each alert as signed JSON to a URL you choose. The URL has to:

- use `https`, on port 443 or 8443;
- use a host name, not an IP address;
- resolve to public IP addresses only. Ladon checks every address and never sends to private or internal networks.

When you add the channel, Ladon first sends a challenge to prove the endpoint is yours. You also get the signing secret, shown only once. Everything about the requests, signatures and retries is in [Webhooks](https://ladon.hackindex.io/docs/webhooks.md).

## Slack

Choose **Slack** when you add a channel and continue to Slack. Slack asks which workspace and channel Ladon may post in. Ladon only asks for permission to post in that one channel, it cannot read anything in your workspace.

Messages show the severity with a coloured dot, the software and title, the CVE and fixed versions, a button to open the alert in Ladon, and the source with its copyright notice. To post in another channel later, use **Connect a channel** on the channel page.

When the Slack app is removed or the channel is archived, Slack answers that the webhook no longer exists. Ladon then switches the channel off and emails the owners and admins.

## Discord

Discord runs on every plan, including Free, so you can run a feed of critical vulnerabilities in a community server. On Free a Discord channel only carries [CVE rule](https://ladon.hackindex.io/docs/cve-rules.md) alerts, not the software watches of your project: add the channel, then link it to a CVE rule of the same project. On Pro and higher it also gets the alerts of your watches, and you choose which alerts, which severity and when, like any other channel. Without a white-label plan, every message keeps its **Open in Ladon** link.

In Discord, open the settings of the channel, then **Integrations**, **Webhooks**, **New Webhook** and **Copy Webhook URL**. Paste the URL in Ladon. It starts with `https://discord.com/api/webhooks/`.

Messages are embeds with a colour per severity. Mentions are switched off, so text from a vulnerability title can never ping your server. For a forum channel, tick **This is a forum channel** and every alert starts a new post.

When the webhook is deleted in Discord, Ladon switches the channel off after the first answer that says so.

## Microsoft Teams

In Teams, open the menu of the channel, choose **Workflows** and the template **Send webhook alerts to a channel**. At the end Teams shows a URL, paste it in Ladon. It contains `environment.api.powerplatform.com`.

Messages are Adaptive Cards with the same details and a button to open the alert in Ladon.

A workflow belongs to the person who made it. When their account is removed, the workflow stops and Ladon switches the channel off. Let someone who stays make it, or a service account.

Ladon only accepts webhook URLs of Slack, Discord and Microsoft Teams in these channels, and stores them encrypted. They work like a password, so Ladon never shows them again after you save.

## When alerts go out

- **Right away**: every alert is sent as soon as it happens. Optionally set **At most per hour**. Above that number, alerts are bundled into one message until the hour is over. Critical alerts always go right away.
- **Bundled**: alerts that arrive close together go out as one message. The first alert starts a wait of 5, 15 or 60 minutes, everything that arrives in that time comes along.
- **Summary**: all alerts in one message at a fixed moment: every hour, every day at a time you choose, or every week on a day and time you choose, in your time zone. Long summaries are split into messages of up to 100 events.

With bundled delivery or a summary you can tick **Send critical alerts right away**, so a critical vulnerability never waits.

The free plan has right away and the daily summary. Bundled delivery, hourly and weekly summaries and sending critical alerts right away are part of the paid plans. When many alerts go out at once, paid plans are sent first.

## Language

Every channel has its own language, English or Dutch, for its emails, chat messages, summaries and tests. A new channel starts in the language of the person who adds it, also through the API, where that is the language of the token owner's HackIndex account. Change it under **Edit**, or with `locale` in the API. A team has no language of its own, so one team can have an English channel for a client and a Dutch one for itself.

The JSON of a webhook has no language. Only the `data.message` of a test and the `reasons` of a [CVE rule](https://ladon.hackindex.io/docs/cve-rules.md) follow the channel.

## Appearance {#appearance}

On Pro and higher you choose what a message in Slack, Discord, Microsoft Teams or an email shows, under **Edit** and then **Message appearance**. The form shows an example of a critical alert while you change it.

- **Details**: leave out the severity, the CVE number, the fixed version, the projects that install it, what changed, or the details and reasons of [CVE rules](https://ladon.hackindex.io/docs/cve-rules.md). The link to the source and the notices of the data always stay, their license asks for them.
- **Layout**: with details, or compact: only the title, the severity and the links.
- **Text before every title**, such as `[Acme]`, up to 30 characters. Summaries get it too.
- **Line color** in Discord: per severity, or one color of your own.
- **Mentions** for critical alerts, or for critical and high: in Discord a role, a person or `@here`, in Slack `@here`, `@channel` or a user group. Copy the ID of a Discord role or person with developer mode on, the ID of a Slack user group starts with `S`.

In the API this is `appearance`, with `hidden`, `layout`, `prefix`, `mentions` (such as `role:123`, `user:123`, `here`, `channel` or `group:S0123ABCDE`), `mention_from` (`critical` or `high`) and `color` (such as `#15803d`, or `null` per severity). After a move to Free the channel keeps working with the standard look, and its choices come back after an upgrade. Webhooks always get the full JSON.

## White-label {#white-label}

On Business and higher, alerts can carry your brand instead of Ladon's. Set it up once per team on the **Brand** tab of the team: a name, a logo, a color, a footer and a reply address. Every channel of every project of the team can use it. Switch it on per channel with **Use the brand of the team** under **Message appearance**.

| Channel         | What changes                                                                                                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Discord         | Your name and logo as sender, your color on messages without a severity                                                                                                                                 |
| Slack           | Your logo and name on top of the message. The sender stays the Ladon app, as Slack wants. To change the sender too, create your own Slack app with an incoming webhook and paste its URL as the channel |
| Microsoft Teams | Your logo and name on top of the card. The sender is already the person who made the workflow                                                                                                           |
| Email           | Your name as sender, your logo on top, your footer and, once confirmed, your reply address. The address stays ours, so the mail arrives                                                                 |

The notices and links of the data sources always stay, their licenses ask for them, and every email notes at the bottom that it was sent via HackIndex Ladon. A new reply address only counts after its owner confirms it through a link. After a move to a lower plan the brand stays saved and channels go back to the look of Ladon, an upgrade brings it back.

## Link to Ladon {#link-to-ladon}

Chat messages and emails link to the alert in Ladon with **Open in Ladon**. Removing that link is part of white-label (Business and higher): switch off **Show Open in Ladon** under **Edit**, or send `link_to_ladon: false` in the API. Without the plan the link always stays, so a free Discord feed keeps pointing back to Ladon. When the link is off the alert only links to its source, and the notices and the licenses link stay. Webhooks always carry the links in their JSON.

## Filters per channel

The channel decides which alerts it sends: its own event types, severity filter and [tag filter](#tags). The software of a project does not choose that, so the lockfiles, the software you added by hand and the common software of a project reach every channel whose filters let the alert through. For example, send everything to a ticket system, and only critical alerts to the on-call address.

A watch you made by hand or through the API keeps its own event types and severity filter, on top of those of the channel. An alert of such a watch only arrives when both let it through.

An alert about a vulnerability only reaches the channels of a project when that project installs an affected version. A project on a fixed version stays quiet, even when another project of the team runs the same software. Software you added to a project by hand counts for the versions you chose.

[CVE rules](https://ladon.hackindex.io/docs/cve-rules.md) are the exception: a rule names its own channels and its conditions decide what goes out, so these filters do not apply to them.

## Routing by tag {#tags}

Give a channel a tag filter and it only gets the alerts of watches with at least one of those tags. Leave it empty and the channel gets the alerts of every watch of the project. For example, send everything about `production` to the on-call Slack channel, and everything to your own ticket system.

Tags are set per watch and per project, see [Watching software](https://ladon.hackindex.io/docs/watches.md#tags). A watch without tags only reaches channels without a tag filter.

## Several projects in one place {#projects}

A channel only hears about its own project. To get the alerts of several projects in the same Slack channel, inbox or endpoint, add a channel in each of those projects with the same address. Each channel keeps its own filters, so one project can send everything and another only critical alerts. Each of those channels counts towards the channels of your plan.

Teams that had channels before projects existed were moved for you. A channel that heard about several or all projects got a copy in each of those projects, with the same address, recipients and settings. Those copies do not take an extra place on your plan.

## Testing

Use **Send test** on the channel page to send a `ping` message. Tests are limited to 5 per minute.

## Delivery log

The channel page shows the last 50 delivery attempts: when, how long it took, the status code and the start of the answer. How long Ladon keeps this log depends on your plan, see [Plans and limits](https://ladon.hackindex.io/docs/plans-and-limits.md).

## When deliveries fail

Ladon retries a failed delivery for about three days. After the third failed attempt the owners and admins of the team get an email. When every delivery fails for five days, or the endpoint answers `410 Gone`, Ladon switches the channel off and tells you. Slack, Discord and Teams channels also switch off when the app answers that the webhook no longer exists. Fix the endpoint and switch it on again on the channel page.

### Sending again {#send-again}

Once the channel is on, **Send again** on the channel page sends every alert that failed or was given up since a moment you choose, up to 30 days back. Tests are left out. The alerts go out within a minute, in their original form, and the delivery log shows how it went. Owners and admins can do this, through the API it is `POST /endpoints/{id}/recover`.

You can also pause a channel yourself. A paused channel receives nothing, and alerts from that time are not sent later.

## Who can manage channels

Owners and admins of a team can add, change and remove the channels of every project of the team, and set up its brand. Members see the alerts of a project but not its channels. See [Teams and security](https://ladon.hackindex.io/docs/teams-and-security.md).

Removing a project removes its channels too.
