kibana-connectors

$27

Authentication

All connector API calls require API key auth or Basic auth. Every mutating request must include the kbn-xsrf header.

kbn-xsrf: true

Required Privileges

Access to connectors is granted based on your privileges to alerting-enabled features. You need all privileges for

Actions and Connectors in Stack Management.

API Reference

Base path: <kibana_url>/api/actions (or /s/<space_id>/api/actions for non-default spaces).

Operation

Method

Endpoint

Create connector

POST

/api/actions/connector/{id}

Update connector

PUT

/api/actions/connector/{id}

Get connector

GET

/api/actions/connector/{id}

Delete connector

DELETE

/api/actions/connector/{id}

Get all connectors

GET

/api/actions/connectors

Get connector types

GET

/api/actions/connector_types

Run connector

POST

/api/actions/connector/{id}/_execute

Creating a Connector

Required Fields

Field

Type

Description

name

string

Display name for the connector

connector_type_id

string

The connector type (e.g., .slack, .email, .webhook, .pagerduty, .jira)

config

object

Type-specific configuration (non-secret settings)

secrets

object

Type-specific secrets (API keys, passwords, tokens)

Example: Create a Slack Connector (Webhook)

curl -X POST "https://my-kibana:5601/api/actions/connector/my-slack-connector" \

  -H "kbn-xsrf: true" \

  -H "Content-Type: application/json" \

  -H "Authorization: ApiKey <your-api-key>" \

  -d '{

    "name": "Production Slack Alerts",

    "connector_type_id": ".slack",

    "config": {},

    "secrets": {

      "webhookUrl": "https://hooks.slack.com/services/T00/B00/XXXX"

    }

  }'

All connector types share the same request structure — only connector_type_id, config, and secrets differ. See the

[Common Connector Type IDs](#common-connector-type-ids) table for available types and their required fields.

Example: Create a PagerDuty Connector

curl -X POST "https://my-kibana:5601/api/actions/connector/my-pagerduty" \

  -H "kbn-xsrf: true" \

  -H "Content-Type: application/json" \

  -H "Authorization: ApiKey <your-api-key>" \

  -d '{

    "name": "PagerDuty Incidents",

    "connector_type_id": ".pagerduty",

    "config": {

      "apiUrl": "https://events.pagerduty.com/v2/enqueue"

    },

    "secrets": {

      "routingKey": "your-pagerduty-integration-key"

    }

  }'

Updating a Connector

PUT /api/actions/connector/{id} replaces the full configuration. connector_type_id is immutable — delete and

recreate to change it.

Listing and Discovering Connectors

# Get all connectors in the current space

curl -X GET "https://my-kibana:5601/api/actions/connectors" \

  -H "Authorization: ApiKey <your-api-key>"

# Get available connector types

curl -X GET "https://my-kibana:5601/api/actions/connector_types" \

  -H "Authorization: ApiKey <your-api-key>"

# Filter connector types by feature (e.g., only those supporting alerting)

curl -X GET "https://my-kibana:5601/api/actions/connector_types?feature_id=alerting" \

  -H "Authorization: ApiKey <your-api-key>"

The GET /api/actions/connectors response includes referenced_by_count showing how many rules use each connector.

Always check this before deleting.

Running a Connector (Test)

Execute a connector action directly, useful for testing connectivity.

curl -X POST "https://my-kibana:5601/api/actions/connector/my-slack-connector/_execute" \

  -H "kbn-xsrf: true" \

  -H "Content-Type: application/json" \

  -H "Authorization: ApiKey <your-api-key>" \

  -d '{

    "params": {

      "message": "Test alert from API"

    }

  }'

Deleting a Connector

curl -X DELETE "https://my-kibana:5601/api/actions/connector/my-slack-connector" \

  -H "kbn-xsrf: true" \

  -H "Authorization: ApiKey <your-api-key>"

Warning: Deleting a connector that is referenced by rules will cause those rule actions to fail silently. Check

referenced_by_count first.

Terraform Provider

Use the elasticstack provider resource elasticstack_kibana_action_connector.

terraform {

  required_providers {

    elasticstack = {

      source  = "elastic/elasticstack"

    }

  }

}

provider "elasticstack" {

  kibana {

    endpoints = ["https://my-kibana:5601"]

    api_key   = var.kibana_api_key

  }

}

resource "elasticstack_kibana_action_connector" "slack" {

  name              = "Production Slack Alerts"

  connector_type_id = ".slack"

  config = jsonencode({})

  secrets = jsonencode({

    webhookUrl = "https://hooks.slack.com/services/T00/B00/XXXX"

  })

}

resource "elasticstack_kibana_action_connector" "index" {

  name              = "Alert Index Writer"

  connector_type_id = ".index"

  config = jsonencode({

    index              = "alert-history"

    executionTimeField = "@timestamp"

  })

  secrets = jsonencode({})

}

Key Terraform notes:

• config and secrets must be JSON-encoded strings via jsonencode()

• Secrets are stored in Terraform state; use a remote backend with encryption and restrict state file access

• Import existing connectors:

terraform import elasticstack_kibana_action_connector.my_connector <space_id>/<connector_id> (use default for the

default space)

• After import, secrets are not populated in state; you must supply them in config

Preconfigured Connectors (On-Prem)

For self-managed Kibana, connectors can be preconfigured in kibana.yml so they are available at startup without manual

creation:

xpack.actions.preconfigured:

  my-slack-connector:

    name: "Production Slack"

    actionTypeId: .slack

    secrets:

      webhookUrl: "https://hooks.slack.com/services/T00/B00/XXXX"

  my-webhook:

    name: "Custom Webhook"

    actionTypeId: .webhook

    config:

      url: "https://api.example.com/alerts"

      method: post

      hasAuth: true

    secrets:

      user: "alert-user"

      password: "secret-password"

Preconfigured connectors cannot be edited or deleted via the API or UI. They show is_preconfigured: true and omit

config and is_missing_secrets from API responses.

Networking Configuration

Customize connector networking (proxies, TLS, certificates) via kibana.yml:

# Global proxy for all connectors

xpack.actions.proxyUrl: "https://proxy.example.com:8443"

# Per-host TLS settings

xpack.actions.customHostSettings:

  - url: "https://api.example.com"

    ssl:

      verificationMode: full

      certificateAuthoritiesFiles: ["/path/to/ca.pem"]

Connectors in Kibana Workflows

Connectors serve as the integration layer across multiple Kibana workflows, not just alerting notifications:

Workflow

Connector Types

Key Pattern

ITSM ticketing

ServiceNow, Jira, IBM Resilient

Create ticket on active, close on Recovered

On-call escalation

PagerDuty, Opsgenie

trigger on active, resolve on Recovered; always set a deduplication key

Case management

Cases (system action)

UI-only; groups alerts into investigation Cases; can auto-push to ITSM

Messaging / awareness

Slack, Teams, Email

onActionGroupChange for incident channels; summaries for monitoring channels

Audit logging

Index

onActiveAlert to write full alert time-series to Elasticsearch

AI workflows

OpenAI, Bedrock, Gemini, AI Connector

Powers Elastic AI Assistant and Attack Discovery; system-managed

Custom integrations

Webhook

Generic HTTP outbound with Mustache-templated JSON body

For detailed patterns, examples, and decision guidance for each workflow, see workflows.md.

Best Practices

-

Use preconfigured connectors for production on-prem. They eliminate secret sprawl, survive Saved Object imports,

and cannot be accidentally deleted. Reserve API-created connectors for dynamic or user-managed scenarios.

-

Test connectors before attaching to rules. Use the _execute endpoint to verify connectivity. A misconfigured

connector causes silent action failures that only appear in the rule's execution history.

-

**Check referenced_by_count before deleting.** Deleting a connector used by active rules causes those actions to

fail. List connectors and verify zero references, or reassign rules to a new connector first.

-

Use the Email domain allowlist. The xpack.actions.email.domain_allowlist setting restricts which email domains

connectors can send to. If you update this list, existing email connectors with recipients outside the new list will

start failing.

-

Secure secrets in Terraform. Connector secrets (API keys, passwords, webhook URLs) are stored in Terraform state.

Use encrypted remote backends (S3+KMS, Azure Blob+encryption, GCS+CMEK) and restrict access to state files. Use

sensitive = true on variables.

-

One connector per service, not per rule. Create a single Slack connector and reference it from multiple rules.

This centralizes secret rotation and reduces duplication.

-

Use Spaces for multi-tenant isolation. Connectors are scoped to a Kibana Space. Create separate spaces for

different teams or environments and configure connectors per space.

-

Monitor connector health. Failed connector executions are logged in the event log index (.kibana-event-log-*).

Connector failures report as successful to Task Manager but fail silently for alert delivery. Check the

Event Log Index for true failure

rates.

-

Always configure a recovery action alongside the active action. Connectors for ITSM and on-call tools

(ServiceNow, Jira, PagerDuty, Opsgenie) support a close/resolve operation. Without a recovery action, incidents

remain open forever.

-

Use deduplication keys for on-call connectors. Set dedupKey (PagerDuty) or alias (Opsgenie) to

{{rule.id}}-{{alert.id}} to ensure the resolve event closes exactly the right incident. Without this, a new

incident is created every time the alert re-fires.

-

Prefer the Cases connector for investigation workflows. When an alert requires investigation with comments,

attachments, and assignees, use Cases rather than a direct Jira/ServiceNow connector. Cases gives you a native

investigation UI and can still push to ITSM via the Case's external connection.

-

Use the Index connector for durable audit trails. The Index connector writes to Elasticsearch, making alert

history searchable and dashboardable. Pair it with an ILM policy on the target index to control retention.

-

Restrict connector access via Action settings. Use xpack.actions.enabledActionTypes to allowlist only the

connector types your organization needs, and xpack.actions.allowedHosts to restrict outbound connections to known

endpoints.

Common Pitfalls

-

**Missing kbn-xsrf header.** All POST, PUT, DELETE requests require kbn-xsrf: true. Omitting it returns a 400

error.

-

**Wrong connector_type_id.** Use the exact string including the leading dot (e.g., .slack, not slack). Discover

valid types via GET /api/actions/connector_types.

-

**Empty secrets object required.** Even for connectors without secrets (e.g., .index, .server-log), you must

provide "secrets": {} in the create request.

-

Connector type is immutable. You cannot change the connector_type_id after creation. Delete and recreate

instead.

-

Secrets lost on export/import. Exporting connectors via Saved Objects strips secrets. After import, connectors

show is_missing_secrets: true and a "Fix" button appears in the UI. You must re-enter secrets manually or via API.

-

Preconfigured connectors cannot be modified via API. Attempting to update or delete a preconfigured connector

returns 400. Manage them exclusively in kibana.yml.

-

Rate limits from third-party services. Connectors that send high volumes of notifications (e.g., one per alert

every minute) can hit Slack, PagerDuty, or email provider rate limits. Use alert summaries and action frequency

controls on the rule side to reduce volume.

-

Connector networking failures. Kibana must be able to reach the connector's target URL. Verify firewall rules,

proxy settings, and DNS resolution. Use xpack.actions.customHostSettings for TLS issues.

-

License requirements. Some connector types require a Gold, Platinum, or Enterprise license. Check the

minimum_license_required field from GET /api/actions/connector_types. A connector that is

enabled_in_config: true but enabled_in_license: false cannot be used.

-

Terraform import does not restore secrets. When importing an existing connector into Terraform, the secrets are

not read back from Kibana. You must provide them in your Terraform configuration, or the next terraform apply will

overwrite them with empty values.

Common Connector Type IDs

Type ID

Name

License

.email

Email

Gold

.slack

Slack (Webhook)

Gold

.slack_api

Slack (API)

Gold

.pagerduty

PagerDuty

Gold

.jira

Jira

Gold

.servicenow

ServiceNow ITSM

Platinum

.servicenow-sir

ServiceNow SecOps

Platinum

.servicenow-itom

ServiceNow ITOM

Platinum

.webhook

Webhook

Gold

.index

Index

Basic

.server-log

Server log

Basic

.opsgenie

Opsgenie

Gold

.teams

Microsoft Teams

Gold

.gen-ai

OpenAI

Enterprise

.bedrock

Amazon Bedrock

Enterprise

.gemini

Google Gemini

Enterprise

.cases

Cases

Platinum

.crowdstrike

CrowdStrike

Enterprise

.sentinelone

SentinelOne

Enterprise

.microsoft_defender_endpoint

Microsoft Defender for Endpoint

Enterprise

.thehive

TheHive

Gold

Note: Use GET /api/actions/connector_types to discover all available types on your deployment along with their

exact minimum_license_required values. Connector types for XSOAR, Jira Service Management, and MCP are available but

may not appear in older API spec versions.

Examples

Create a Slack connector: "Set up Slack notifications for our alerts." POST /api/actions/connector with

connector_type_id: ".slack" and secrets.webhookUrl. Use the returned connector id in rule actions.

Test a connector before attaching to rules: "Verify the PagerDuty connector works."

POST /api/actions/connector/{id}/_execute with a minimal params object to confirm connectivity before adding to any

rule.

Audit connector usage before deletion: "Remove the old email connector." GET /api/actions/connectors, inspect

referenced_by_count — if non-zero, reassign the referencing rules first, then DELETE /api/actions/connector/{id}.

Guidelines

• Include kbn-xsrf: true on every POST, PUT, and DELETE; omitting it returns 400.

• connector_type_id is immutable — delete and recreate to change connector type.

• Always pass "secrets": {} even for connectors with no secrets (e.g., .index, .server-log).

• Check referenced_by_count before deleting; a deleted connector silently breaks all referencing rule actions.

• Connectors are space-scoped; prefix paths with /s/<space_id>/api/actions/ for non-default Kibana Spaces.

• Secrets are write-only: not returned by GET and stripped on Saved Object export/import; always re-supply after import.

• Test every new connector with _execute before attaching to rules; connector failures in production are silent.

Additional Resources

• Kibana Connectors API Reference

• Connectors Overview

• Preconfigured Connectors

• Alerting Settings (Action Config)

• Terraform: elasticstack_kibana_action_connector

• Terraform: Managing Kibana Rule and Connector Resources