Kibana Connectors

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 imports, and cannot be accidentally deleted. Reserve API-created connectors for dynamic or user-managed scenarios.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Empty `secrets` object required. Even for connectors without secrets (e.g., .index, .server-log), you must provide "secrets": {} in the create request.

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

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

6. Preconfigured connectors cannot be modified via API. Attempting to update or delete a preconfigured connector returns 400. Manage them exclusively in kibana.yml.

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

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

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

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

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

Connectors and Actions in Rules: Design Reference

Action Structure

Each action in a rule references a connector and has its own frequency configuration:

{
  "id": "<connector-id>",
  "group": "query matched",
  "params": { "message": "{{rule.name}} fired: {{context.reason}}" },
  "frequency": {
    "summary": false,
    "notify_when": "onActionGroupChange",
    "throttle": null
  }
}

• group: The action group (e.g., "query matched", "threshold met", "Recovered"). Each rule type defines its

valid groups. Discover them via GET /api/alerting/rule_types.

• frequency.summary: true for a summary of all alerts; false to run per-alert.
• frequency.notify_when: onActionGroupChange | onActiveAlert | onThrottleInterval.
• frequency.throttle: Minimum interval between repeated notifications (e.g., "10m"). Only applies when notify_when

is onThrottleInterval.

Deprecated: Do not set notify_when or throttle at the rule level. These are deprecated in favour of per-action

frequency objects and will be auto-converted if the rule is edited in the Kibana UI.

Action Variables (Mustache Templates)

Action params use Mustache syntax to inject rule and alert values at runtime.

Common variables (all rule types)

Per-alert variables (summary: false)

Summary variables (summary: true)

Iterating over arrays

For rule types that return multiple hits (e.g., ES Query rules):

{{#context.hits}} - {{_source.message}} ({{_source.@timestamp}})
{{/context.hits}}

Debugging templates

Use {{{.}}} in any action body to dump the entire variable context as a JSON object. Remove before enabling the rule in production.

Mustache Lambdas

Kibana provides built-in lambdas for advanced template rendering:

# Round a numeric value
{{#EvalMath}} round(context.value, 2) {{/EvalMath}}

# Format a date in a specific timezone
{{#FormatDate}} {{{date}}} ; America/New_York ; YYYY-MM-DD HH:mm {{/FormatDate}}

# Render numbers with locale formatting
{{#FormatNumber}} {{{context.value}}} ; en-US ; maximumFractionDigits: 2 {{/FormatNumber}}

# Build clean JSON from Hjson for Webhook connectors
{{#ParseHjson}}
{
  ruleId:   "{{rule.id}}"
  ruleName: "{{rule.name}}"
  value:    "{{context.value}}"
}
{{/ParseHjson}}

ParseHjson is especially useful with Webhook connectors — it allows comments, unquoted keys, and trailing commas, avoiding strict JSON escaping issues.

Recovery Actions

Always configure a recovery action alongside the active action to close incidents automatically. Use the Recovered action group:

{
  "actions": [
    {
      "id": "my-pagerduty",
      "group": "threshold met",
      "params": { "eventAction": "trigger", "dedupKey": "{{rule.id}}-{{alert.id}}", "summary": "{{rule.name}} firing" },
      "frequency": { "summary": false, "notify_when": "onActionGroupChange" }
    },
    {
      "id": "my-pagerduty",
      "group": "recovered",
      "params": {
        "eventAction": "resolve",
        "dedupKey": "{{rule.id}}-{{alert.id}}",
        "summary": "{{rule.name}} resolved"
      },
      "frequency": { "summary": false, "notify_when": "onActionGroupChange" }
    }
  ]
}

PagerDuty and Opsgenie have dedicated resolve/close event actions for recovery. ServiceNow and Jira connectors have a Close alert sub-action. Without a recovery action, incidents remain open indefinitely.

Multi-Channel Action Design

Attach multiple actions to a single rule to route to different channels based on purpose:

{
  "actions": [
    {
      "id": "slack-connector",
      "group": "query matched",
      "params": { "message": ":warning: *{{rule.name}}* fired\n> {{context.reason}}" },
      "frequency": { "summary": false, "notify_when": "onActionGroupChange" }
    },
    {
      "id": "pagerduty-connector",
      "group": "query matched",
      "params": {
        "eventAction": "trigger",
        "severity": "critical",
        "summary": "{{rule.name}}",
        "dedupKey": "{{rule.id}}-{{alert.id}}"
      },
      "frequency": { "summary": false, "notify_when": "onActionGroupChange" }
    },
    {
      "id": "index-connector",
      "group": "query matched",
      "params": { "documents": [{ "rule": "{{rule.name}}", "ts": "{{date}}", "value": "{{context.value}}" }] },
      "frequency": { "summary": false, "notify_when": "onActiveAlert" }
    }
  ]
}

Pattern: Slack + PagerDuty fire once on status change (onActionGroupChange). Index connector fires every check interval (onActiveAlert) to build a complete time-series audit log.

Choosing notify_when per Channel

Connectors in Kibana Workflows

Preview feature — Kibana Workflows is available from Elastic Stack 9.3 and Elastic Cloud Serverless. APIs and

behaviour may change.

Connectors serve as the integration layer across several Kibana workflows beyond basic alerting.

Workflow 0: Alerting Rules as Workflow Triggers

Kibana Workflows can be driven directly by alerting rules. When a rule fires, the workflow receives the full alert payload and can act on it using steps.

Alert trigger YAML definition

name: Alert Response Workflow
description: Automated triage and response for alerting rules
enabled: true
triggers:
  - type: alert
steps:
  - name: log_alert
    type: console
    with:
      message: "Rule '{{ event.alerts[0].kibana.alert.rule.name }}' fired"
      details: "{{ event | json:2 }}"

Available alert context fields

All alert data is accessible via {{ event.alerts[N] }} in workflow step parameters:

For summary-frequency actions (multiple alerts), iterate:

message: "{{ event.alerts | size }} alerts fired"

Three-step alert response pattern

name: Alert Triage
enabled: true
triggers:
  - type: alert
steps:
  - name: enrich
    type: ai.prompt
    with:
      connectorId: "<llm-connector-id>"
      prompt: |
        Summarise this security alert and suggest next steps:
        Rule: {{ event.alerts[0].kibana.alert.rule.name }}
        Reason: {{ event.alerts[0].kibana.alert.reason }}
        Host: {{ event.alerts[0].host.name }}

  - name: create_case
    type: kibana.createCaseDefaultSpace
    with:
      title: "{{ event.alerts[0].kibana.alert.rule.name }}"
      description: "{{ steps.enrich.output }}"
      tags: ["automated", "workflow"]
      severity: "critical"
      connector:
        id: "none"
        name: "none"
        type: ".none"

  - name: mute_alert
    type: kibana.request
    with:
      method: POST
      path:
        /api/alerting/rule/{{ event.alerts[0].kibana.alert.rule.uuid }}/alert/{{ event.alerts[0].kibana.alert.uuid
        }}/_mute

Pitfalls specific to alert triggers

• Only enabled workflows appear in the rule action picker. Workflows must be set to enabled: true in YAML before

they are selectable from a rule.

• Threshold detection rules have limited source field access. Original event fields from the matching documents are

not always available in event.alerts[0]. Use ES Query rules if you need source document fields in the workflow.

• `params: {}` is valid. Unlike connector-based actions, workflow actions do not need params populated from the rule

side — context flows automatically through the event object in the workflow definition.

• Workflows run under the API key of the user who saved the rule action. If that user's permissions change, the

workflow may fail. Re-save the rule action to refresh the associated key.

Workflow 1: Alert → Incident Ticket (ITSM)

Use ServiceNow ITSM, Jira, or IBM Resilient connectors to automatically open tickets when a rule fires and close them on recovery.

Pattern:

• Active action group → connector creates a ticket (Jira issue, ServiceNow incident)
• Recovered action group → connector transitions the ticket to resolved/closed

Tips:

• Use {{alert.id}} as the deduplication key to avoid duplicate tickets for the same alert instance.
• Set notify_when: onActionGroupChange on both actions so tickets are created and closed exactly once per alert

lifecycle.

• ServiceNow ITSM supports correlation_id to link Kibana alerts to existing incidents — use {{rule.id}}-{{alert.id}}

as the correlation ID.

Workflow 2: Alert → On-Call Escalation (PagerDuty / Opsgenie)

Use PagerDuty or Opsgenie connectors to trigger and resolve incidents in your on-call platform.

PagerDuty deduplication key: Set dedupKey to {{rule.id}}-{{alert.id}} so PagerDuty groups multiple trigger events for the same alert into one incident, and the resolve event closes the right one.

{
  "group": "threshold met",
  "params": {
    "eventAction": "trigger",
    "dedupKey": "{{rule.id}}-{{alert.id}}",
    "severity": "critical",
    "summary": "{{context.reason}}"
  }
}

{
  "group": "recovered",
  "params": {
    "eventAction": "resolve",
    "dedupKey": "{{rule.id}}-{{alert.id}}"
  }
}

For Opsgenie, use alias instead of dedupKey. The close event action (not resolve) closes Opsgenie alerts.

Workflow 3: Alert → Kibana Case (Case Management)

The Cases connector creates Kibana Cases from alerts. It is a system action — it cannot be created, edited, or deleted via the API or UI. It is only available when creating a rule in the Kibana UI.

Key behaviors:

• All alerts from a rule attach to the same Case by default; use a grouping field (e.g., host.name) to create one Case

per alert group.

• A 7-day time window prevents duplicate Cases; alerts within the window are attached to the existing Case.
• If the Case is connected to an external ITSM (ServiceNow, Jira), enable Auto-push to sync the Case to that system

automatically.

• Enable Re-open closed cases if you want re-activated alerts to reopen their associated Case.
• Set a maximum case count to limit Case creation if the rule can fire for many distinct entities simultaneously.

Use Cases connector when: you want a full investigation workflow with comments, attachments, SLA timers, and assignees — rather than just a point notification.

Do not use Cases connector when: you need low-latency paging or automated ticket creation via API/Terraform (Cases connector is UI-only).

Workflow 4: Alert → Messaging (Slack / Teams / Email)

Use messaging connectors for awareness notifications that don't require a formal incident response.

Best message template pattern (Slack example):

:red_circle: *{{rule.name}}* fired
*Reason:* {{context.reason}}
*Time:* {{#FormatDate}} {{{date}}} ; America/New_York {{/FormatDate}}
*Details:* {{{rule.url}}}

Alert summary for busy rules:

{
  "frequency": {
    "summary": true,
    "notify_when": "onThrottleInterval",
    "throttle": "15m"
  },
  "params": {
    "message": "{{alerts.new.count}} new, {{alerts.ongoing.count}} ongoing, {{alerts.recovered.count}} recovered alerts for rule *{{rule.name}}*"
  }
}

Channel strategy:

• #incidents channel → onActionGroupChange, per-alert, no summaries (low noise, high signal)
• #monitoring channel → summary every 15–30m (onThrottleInterval, summary: true)
• On-call (PagerDuty/Opsgenie) → onActionGroupChange, always with recovery action

Email-specific: Set server.publicBaseUrl in kibana.yml so {{{rule.url}}} generates a valid deep link in email footers. Without this, email links are empty strings.

Workflow 5: Alert → Audit Log (Index Connector)

Use the Index connector to write every alert occurrence to an Elasticsearch index for dashboards, SLA tracking, and audit trails.

{
  "group": "threshold met",
  "params": {
    "documents": [
      {
        "rule_name": "{{rule.name}}",
        "rule_id": "{{rule.id}}",
        "alert_id": "{{alert.id}}",
        "alert_group": "{{alert.actionGroup}}",
        "value": "{{context.value}}",
        "reason": "{{context.reason}}",
        "timestamp": "{{date}}"
      }
    ]
  },
  "frequency": { "summary": false, "notify_when": "onActiveAlert" }
}

Set notify_when: onActiveAlert so every rule run that finds the condition active writes a record — giving a complete time-series of the alert, not just the first occurrence. Pair the target index with an ILM policy to control retention separately from the 90-day event log default.

Workflow 6: Connectors in AI / LLM Workflows

LLM connectors (OpenAI, Amazon Bedrock, Google Gemini) power the Elastic AI Assistant and Attack Discovery features in Security and Observability. These are system connectors used internally by Kibana's AI features.

Setup recommendations:

• Use the AI Connector type (.gen-ai) for flexibility across providers; it supports switching between

OpenAI-compatible APIs without recreating the connector.

• Only one LLM connector can be active at a time per Kibana Space for the AI Assistant. Configure it in **Stack

Management > AI Assistants**.

• Restrict LLM connector access to the relevant features via Space privilege settings. Prevent general users from

executing LLM connectors directly.

• Rotate LLM API keys regularly — they are high-value, rate-limited credentials.
• Monitor token usage and rate limits via the external provider's dashboard; Kibana does not currently expose

per-connector token consumption metrics.

Workflow 7: Webhook for Custom Integrations

Use the generic Webhook connector when no first-party connector exists for your target system.

Best practices:

• Use {{#ParseHjson}} to build the JSON payload cleanly without strict JSON escaping:

  {{#ParseHjson}}
  {
    ruleId:   "{{rule.id}}"
    ruleName: "{{rule.name}}"
    alertId:  "{{alert.id}}"
    reason:   "{{context.reason}}"
  }
  {{/ParseHjson}}

• Use triple braces {{{variable}}} only when you are certain the value is already properly escaped for the target

system (e.g., a URL). For JSON payloads, double braces are safe because Kibana escapes JSON-unsafe characters automatically.

• Set hasAuth: true in the connector config and provide credentials in secrets rather than embedding tokens in the

URL or body.

• Add a Content-Type: application/json header in the connector config so the target system parses the body correctly.