Kibana Connectors

Core Concepts

Connectors store connection information for Elastic services and third-party systems. Alerting rules use connectors to route actions (notifications) when rule conditions are met. Connectors are managed per Kibana Space and can be shared across all rules within that space.

Connector Categories

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

Creating a Connector

Required Fields

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 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:

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

Best Practices

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