# MessagingConnection

One destination the messaging centre can send to: a Slack channel, a Microsoft Teams workflow, a Discord or Google Chat incoming webhook, a Jira site.

One destination the messaging centre can send to: a Slack channel, a Microsoft Teams workflow, a Discord or Google Chat incoming webhook, a Jira site, or a signed webhook. MessagingRoute targets, AlertTrigger, ScheduledReport and DetectionRule actions name it by metadata.name. Its credential (a webhook URL, a Jira API token, a Slack bot token) is kept in the tenant's secrets vault as a connector entry, never in the document, an export or a plan. A slack connection is authorized in a browser: apply returns status.phase AwaitingAuthorization and status.authorizationUrl, and the connection sends nothing until a person installs the Vulnesis Slack app from that URL. The type and a Jira site cannot change; declare a new connection under another name instead. Deleting it revokes its vault entry and removes it from every route that targets it. GitHub Issues connections come from the GitHub App installation and cannot be declared here, but a route can still target one by the name export gives it.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `MessagingConnection` |
| Group | [Integrations](/platform-iac/kinds/catalogue.md#integrations) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | many, keyed by `metadata.name` |
| Token and role | An owner, or a service account with the developer role (its ApiKey), or an Authentik access token for either. A member is refused with HTTP 403. See [Credentials for automation](/platform-iac/reference/config-api.md#credentials-for-automation). |
| Secret fields | `spec.jira.apiToken`, `spec.url`: read on the client from `valueFrom`, sent once, never exported or shown in a plan |
| Terraform resource | [`vulnetix_messaging_connection`](/platform-iac/terraform/resources.md#vulnetix_messaging_connection), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.168.0 and later. |
| Pinned schema | [`v1.19.1/MessagingConnection.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/MessagingConnection.schema.json) |
| Newest schema | [`latest/MessagingConnection.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/MessagingConnection.schema.json) |
| First released in | [`v1.5.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.5.0) |
| Print the built-in copy | `vulnetix config schema MessagingConnection` |

## Minimal

Only the fields the kind requires. From `examples/MessagingConnection/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/MessagingConnection.schema.json
# A Slack connection needs nothing else: apply returns status.authorizationUrl,
# where a person installs the Vulnesis Slack app into the workspace.
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: security-slack
spec:
  type: slack
```

**HCL** (resource `vulnetix_messaging_connection`)

```hcl
# Only the arguments the kind requires. From config-schemas examples/MessagingConnection/minimal.yaml.

resource "vulnetix_messaging_connection" "security_slack" {
  name = "security-slack"
  type = "slack"
}
```

Every field that has a schema default, set to that default: [`terraform/messaging_connection.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/messaging_connection.tf) and [`yaml/MessagingConnection.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/MessagingConnection.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/MessagingConnection.schema.json
# A Slack connection needs nothing else: apply returns status.authorizationUrl,
# where a person installs the Vulnesis Slack app into the workspace.
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: security-slack
spec:
  type: slack
EOF
```

## Advanced

Every field the kind supports, with a `when` expression where it takes one. From `examples/MessagingConnection/advanced.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/MessagingConnection.schema.json
# One connection of each shape. Credentials are read from the environment by
# the client and kept in the tenant's secrets vault.
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: security-slack
  labels:
    team: security
  annotations:
    note: Install the Slack app from status.authorizationUrl after the first apply.
spec:
  type: slack
  displayName: Security alerts (Slack)
  paused: false
  slack:
    channelId: C0123456789
    channelName: sec-alerts
---
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: platform-teams
spec:
  type: teams
  displayName: Platform team (Teams)
  url:
    env: VULNESIS_TEAMS_WEBHOOK_URL
---
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: appsec-jira
spec:
  type: jira
  displayName: AppSec Jira
  jira:
    siteUrl: https://acme.atlassian.net
    email: appsec-bot@acme.example
    apiToken:
      env: VULNESIS_JIRA_API_TOKEN
    defaultProjectKey: SEC
    defaultIssueType: Bug
---
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: siem-webhook
spec:
  type: webhook
  displayName: SIEM intake
  paused: true
  url:
    env: VULNESIS_SIEM_WEBHOOK_URL
```

**HCL** (resource `vulnetix_messaging_connection`)

```hcl
# Every argument the kind supports. From config-schemas examples/MessagingConnection/advanced.yaml.

variable "platform_teams_url" {
  type      = string
  sensitive = true
  ephemeral = true
}
variable "appsec_jira_jira_api_token" {
  type      = string
  sensitive = true
  ephemeral = true
}
variable "siem_webhook_url" {
  type      = string
  sensitive = true
  ephemeral = true
}

resource "vulnetix_messaging_connection" "security_slack" {
  name         = "security-slack"
  display_name = "Security alerts (Slack)"
  paused       = false
  slack = {
    channel_id   = "C0123456789"
    channel_name = "sec-alerts"
  }
  type = "slack"
  labels = {
    team = "security"
  }
  annotations = {
    note = "Install the Slack app from status.authorizationUrl after the first apply."
  }
}

resource "vulnetix_messaging_connection" "platform_teams" {
  name           = "platform-teams"
  display_name   = "Platform team (Teams)"
  type           = "teams"
  url_wo         = var.platform_teams_url
  url_wo_version = 1
}

resource "vulnetix_messaging_connection" "appsec_jira" {
  name         = "appsec-jira"
  display_name = "AppSec Jira"
  jira = {
    api_token_wo         = var.appsec_jira_jira_api_token
    api_token_wo_version = 1
    default_issue_type   = "Bug"
    default_project_key  = "SEC"
    email                = "appsec-bot@acme.example"
    site_url             = "https://acme.atlassian.net"
  }
  type = "jira"
}

resource "vulnetix_messaging_connection" "siem_webhook" {
  name           = "siem-webhook"
  display_name   = "SIEM intake"
  paused         = true
  type           = "webhook"
  url_wo         = var.siem_webhook_url
  url_wo_version = 1
}
```

Every field that has a schema default, set to that default: [`terraform/messaging_connection.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/messaging_connection.tf) and [`yaml/MessagingConnection.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/MessagingConnection.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
export VULNESIS_TEAMS_WEBHOOK_URL=...   # read on this machine by valueFrom, never written to the document
export VULNESIS_JIRA_API_TOKEN=...   # read on this machine by valueFrom, never written to the document
export VULNESIS_SIEM_WEBHOOK_URL=...   # read on this machine by valueFrom, never written to the document
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/MessagingConnection.schema.json
# One connection of each shape. Credentials are read from the environment by
# the client and kept in the tenant's secrets vault.
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: security-slack
  labels:
    team: security
  annotations:
    note: Install the Slack app from status.authorizationUrl after the first apply.
spec:
  type: slack
  displayName: Security alerts (Slack)
  paused: false
  slack:
    channelId: C0123456789
    channelName: sec-alerts
---
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: platform-teams
spec:
  type: teams
  displayName: Platform team (Teams)
  url:
    env: VULNESIS_TEAMS_WEBHOOK_URL
---
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: appsec-jira
spec:
  type: jira
  displayName: AppSec Jira
  jira:
    siteUrl: https://acme.atlassian.net
    email: appsec-bot@acme.example
    apiToken:
      env: VULNESIS_JIRA_API_TOKEN
    defaultProjectKey: SEC
    defaultIssueType: Bug
---
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: siem-webhook
spec:
  type: webhook
  displayName: SIEM intake
  paused: true
  url:
    env: VULNESIS_SIEM_WEBHOOK_URL
EOF
```

## Fields

Paths use dots for nesting and `[]` for the items of a list. **Required** means required whenever the parent object is present. A default is what the server uses when the field is left out.

| Field | Type | Required | Default | Allowed values | Secret | Description |
|---|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` |  | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `MessagingConnection` |  | Always MessagingConnection. |
| <span id="metadata"></span>`metadata` | object | yes |  | no other keys |  |  |
| <span id="metadata-name"></span>`metadata.name` | string | yes |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` |  | The object's name, unique per kind within a tenant. It is the natural key: plan, apply, export and the Terraform provider all address an object by kind and name. |
| <span id="metadata-org"></span>`metadata.org` | string | no |  | format `uuid` |  | The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant. |
| <span id="metadata-labels"></span>`metadata.labels` | object | no |  | map of string to string (length 0 to 256); keys match `^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$` |  | Free key/value labels. Stored with the object, never interpreted by the server. |
| <span id="metadata-annotations"></span>`metadata.annotations` | object | no |  | map of string to string (length 0 to 4096) |  | Free key/value notes for people and tools, such as a ticket link. |
| <span id="spec"></span>`spec` | object | yes |  | no other keys |  |  |
| <span id="spec-type"></span>`spec.type` | string | yes |  | `slack`, `teams`, `discord`, `google_chat`, `jira`, `webhook` |  | The provider. slack: a channel in a workspace that installs the Vulnesis Slack app. teams: a Microsoft Teams Workflows (Power Automate) incoming webhook. discord and google_chat: an incoming webhook. jira: issues in a Jira Cloud site, with an API token. webhook: an HTTPS endpoint of yours that receives each message signed with the Standard Webhooks scheme. It cannot change once the connection exists. |
| <span id="spec-displayName"></span>`spec.displayName` | string | no |  | length 1 to 120 |  | The label the console shows. Defaults to metadata.name. |
| <span id="spec-paused"></span>`spec.paused` | boolean | no | `false` |  |  | Stop sending to this connection without removing it. A connection the server stopped after repeated failures, or whose vault entry was revoked, is reported in status.connectionStatus; supplying its credential again starts it. |
| <span id="spec-url"></span>`spec.url` | object | no |  | 1 to 1 keys; no other keys | yes | Where the client reads the URL messages are posted to, for teams, discord, google_chat and webhook. A Discord URL is on discord.com or discordapp.com, a Google Chat URL on chat.googleapis.com, and a Teams URL on logic.azure.com, environment.api.powerplatform.com or webhook.office.com; every URL is https. The URL is the credential, so it is kept in the vault and only a masked form is shown. Required when the connection is created; left out later, the stored URL is kept. |
| <span id="spec-url-env"></span>`spec.url.env` | string | no |  | pattern `^[A-Za-z_][A-Za-z0-9_]*$` |  | Name of an environment variable. |
| <span id="spec-url-file"></span>`spec.url.file` | string | no |  | length 1 to any |  | Path to a file holding the value. Trailing newlines are trimmed. |
| <span id="spec-slack"></span>`spec.slack` | object | no |  | no other keys |  | The channel a slack connection posts to. The workspace is the one the app is installed into from status.authorizationUrl. |
| <span id="spec-slack-channelId"></span>`spec.slack.channelId` | string | no |  | pattern `^[A-Z0-9]{2,30}$` |  | The Slack channel id (C0123456789). Left out, messages need a channel on each route target. |
| <span id="spec-slack-channelName"></span>`spec.slack.channelName` | string | no |  | length 0 to 200 |  | The channel's name, for display only. |
| <span id="spec-jira"></span>`spec.jira` | object | no |  | no other keys |  | The Jira Cloud site a jira connection opens issues in, and the account it acts as. |
| <span id="spec-jira-siteUrl"></span>`spec.jira.siteUrl` | string | yes |  | pattern `^https://[A-Za-z0-9-]+\.atlassian\.net/?$` |  | The site, https://<site>.atlassian.net, with no path. It cannot change once the connection exists. |
| <span id="spec-jira-email"></span>`spec.jira.email` | string | yes |  | format `email`; length 0 to 320 |  | The Atlassian account the API token belongs to. |
| <span id="spec-jira-apiToken"></span>`spec.jira.apiToken` | object | no |  | 1 to 1 keys; no other keys | yes | Where the client reads the account's API token. Jira is asked who the token belongs to before the connection is saved. Required when the connection is created; left out later, the stored token is kept. |
| <span id="spec-jira-apiToken-env"></span>`spec.jira.apiToken.env` | string | no |  | pattern `^[A-Za-z_][A-Za-z0-9_]*$` |  | Name of an environment variable. |
| <span id="spec-jira-apiToken-file"></span>`spec.jira.apiToken.file` | string | no |  | length 1 to any |  | Path to a file holding the value. Trailing newlines are trimmed. |
| <span id="spec-jira-defaultProjectKey"></span>`spec.jira.defaultProjectKey` | string | no |  | pattern `^[A-Za-z][A-Za-z0-9_]{0,19}$` |  | The project a route target opens issues in when it names none. Stored upper case. |
| <span id="spec-jira-defaultIssueType"></span>`spec.jira.defaultIssueType` | string | no |  | length 1 to 60 |  | The issue type a route target uses when it names none, such as Bug or Task. |

## Rules

Conditions the schema enforces beyond each field's own type. `vulnetix config validate` and the engine's plan report a document that breaks one.

| On | Rule |
|---|---|
| `spec` | When `type` is `slack`: `url` is not allowed and `jira` is not allowed. |
| `spec` | When `type` is `jira`: `jira` is required, `url` is not allowed and `slack` is not allowed. |
| `spec` | When `type` is one of `teams`, `discord`, `google_chat`, `webhook`: `slack` is not allowed and `jira` is not allowed. |

## Applying this kind

- **Command.** `vulnetix config apply -f <file>`; the CLI line above says from which release. Plan first with [`vulnetix config plan`](/platform-iac/cli/plan.md): it shows each object as create, update, delete or no change, with a `planHash` that apply then holds to. Apply writes in one transaction.
- **Manager.** Each object records the manager that applied it (`terraform`, `console` or `gitops:<repo>`). `--prune` deletes only objects its own manager owns. See [The manager](/platform-iac/cli/plan.md#the-manager) and the [config engine](/platform-iac/reference/engine.md).
- **Status.** A Slack connection reports phase `AwaitingAuthorization` with the install URL until someone authorizes it in a browser. A webhook's signing secret is shown once, in the apply that creates it. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#status-phases).

## How apply treats it

- Created, updated and deleted through the messaging centre's writers, now transaction scoped. The URL and the Jira token are `valueFrom` secrets kept in the vault as the Resolve Platform keeps them. Each vault write registers its undo.
- A Slack connection is created paused with no credential and reports `AwaitingAuthorization` with the install URL until someone authorizes it in a browser.
- A webhook's signing secret is shown once, in the apply that creates it.
- The type cannot change. Names live in `ConfigManagedObject`.

## Terraform and OpenTofu

The resource is `vulnetix_messaging_connection` in the `vulnetix/resolve` provider. Its arguments are the `spec` in snake case, beside `name`, `labels` and `annotations` from `metadata`. The Minimal and Advanced HCL are above. The provider's own reference is [vulnetix_messaging_connection](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/messaging_connection).

Import an object that already exists by its name:

```shell
# Import an existing MessagingConnection by its name (metadata.name).
terraform import vulnetix_messaging_connection.security_slack security-slack
```

A secret is two arguments, never stored in the plan or the state: `api_token_wo` (write-only) and `api_token_wo_version`, `url_wo` (write-only) and `url_wo_version`. Change the version number to send a new value. See [Secrets](/platform-iac/terraform.md#secrets).

Install, authentication and how state is read: [Terraform and OpenTofu](/platform-iac/terraform.md).

Check a file with `vulnetix config validate -f <file>`. See [Validate documents](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
