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. Fields, YAML, HCL and CLI samples, and how apply treats it.

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 Vulnetix 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
Status	Served. The config engine plans and applies it.
Objects per tenant	many, keyed by `metadata.name`
Token and role	An owner or admin session, or a `vmt_` config management token with the owner or admin role that lists `MessagingConnection` in its kinds. See Management tokens.
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`, imported by name (see Terraform and OpenTofu)
CLI	`vulnetix config apply`, CLI v3.168.0 and later.
Pinned schema	`v1.15.0/MessagingConnection.schema.json`
Newest schema	`latest/MessagingConnection.schema.json`
First released in	`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-language-server: $schema=https://github.com/Vulnetix/config-schemas/releases/latest/download/MessagingConnection.schema.json
# A Slack connection needs nothing else: apply returns status.authorizationUrl,
# where a person installs the Vulnetix Slack app into the workspace.
apiVersion: vulnetix.com/v1
kind: MessagingConnection
metadata:
  name: security-slack
spec:
  type: slack

HCL (resource vulnetix_messaging_connection)

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

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

CLI (applies it)

export VULNETIX_CONFIG_TOKEN=vmt_...   # a config management token
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnetix/config-schemas/releases/latest/download/MessagingConnection.schema.json
# A Slack connection needs nothing else: apply returns status.authorizationUrl,
# where a person installs the Vulnetix 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-language-server: $schema=https://github.com/Vulnetix/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: VULNETIX_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: VULNETIX_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: VULNETIX_SIEM_WEBHOOK_URL

HCL (resource vulnetix_messaging_connection)

# 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
}

CLI (applies it)

export VULNETIX_CONFIG_TOKEN=vmt_...   # a config management token
export VULNETIX_TEAMS_WEBHOOK_URL=...   # read on this machine by valueFrom, never written to the document
export VULNETIX_JIRA_API_TOKEN=...   # read on this machine by valueFrom, never written to the document
export VULNETIX_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/Vulnetix/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: VULNETIX_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: VULNETIX_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: VULNETIX_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
`apiVersion`	string	yes		exactly `vulnetix.com/v1`		The document format version. Every kind in this release is vulnetix.com/v1.
`kind`	string	yes		exactly `MessagingConnection`		Always MessagingConnection.
`metadata`	object	yes		no other keys
`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.
`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.
`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.
`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.
`spec`	object	yes		no other keys
`spec.type`	string	yes		`slack`, `teams`, `discord`, `google_chat`, `jira`, `webhook`		The provider. slack: a channel in a workspace that installs the Vulnetix 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.
`spec.displayName`	string	no		length 1 to 120		The label the console shows. Defaults to metadata.name.
`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.
`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.
`spec.url.env`	string	no		pattern `^[A-Za-z_][A-Za-z0-9_]*$`		Name of an environment variable.
`spec.url.file`	string	no		length 1 to any		Path to a file holding the value. Trailing newlines are trimmed.
`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.
`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.
`spec.slack.channelName`	string	no		length 0 to 200		The channel’s name, for display only.
`spec.jira`	object	no		no other keys		The Jira Cloud site a jira connection opens issues in, and the account it acts as.
`spec.jira.siteUrl`	string	yes		pattern `^https://[A-Za-z0-9-]+\.atlassian\.net/?$`		The site, https://.atlassian.net, with no path. It cannot change once the connection exists.
`spec.jira.email`	string	yes		format `email`; length 0 to 320		The Atlassian account the API token belongs to.
`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.
`spec.jira.apiToken.env`	string	no		pattern `^[A-Za-z_][A-Za-z0-9_]*$`		Name of an environment variable.
`spec.jira.apiToken.file`	string	no		length 1 to any		Path to a file holding the value. Trailing newlines are trimmed.
`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.
`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: 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 and the config engine.
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.

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 console 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.

Import an object that already exists by its name:

# 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.

Install, authentication and how state is read: Terraform and OpenTofu.

Check a file with vulnetix config validate -f <file>. See Validate documents. In an editor, start the file with the schema comment.