Manage notification connectors

curl -X POST http://localhost:5080/api/v1/notify/connectors \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '{
    "name": "Operations webhook",
    "connector_type": "webhook",
    "config": {
      "url": "https://hooks.example.com/molesignal",
      "method": "post",
      "headers": { "Authorization": "Bearer <token>" },
      "timeout_secs": 5
    }
  }'

{
  "id": "3KEDlokKjNmves95sRzL8tXpflY",
  "organization_id": "<organization-id>",
  "name": "Operations webhook",
  "connector_type": "webhook",
  "config": {
    "url": "***",
    "method": "post",
    "headers": "***",
    "timeout_secs": 5
  },
  "capabilities": {
    "direct_user": true,
    "group": true,
    "rich_text": true,
    "interactive": false,
    "acknowledgement": false,
    "attachments": false
  },
  "enabled": true,
  "status": "unknown",
  "last_tested_at": null,
  "last_test_status": null,
  "last_test_error": null,
  "created_at": 1790000000000000,
  "updated_at": 1790000000000000
}

curl -X POST http://localhost:5080/api/v1/notify/connectors \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '{
    "name": "Operations webhook",
    "connector_type": "webhook",
    "config": {
      "url": "https://hooks.example.com/molesignal",
      "method": "post",
      "headers": { "Authorization": "Bearer <token>" },
      "timeout_secs": 5
    }
  }'

{
  "id": "3KEDlokKjNmves95sRzL8tXpflY",
  "organization_id": "<organization-id>",
  "name": "Operations webhook",
  "connector_type": "webhook",
  "config": {
    "url": "***",
    "method": "post",
    "headers": "***",
    "timeout_secs": 5
  },
  "capabilities": {
    "direct_user": true,
    "group": true,
    "rich_text": true,
    "interactive": false,
    "acknowledgement": false,
    "attachments": false
  },
  "enabled": true,
  "status": "unknown",
  "last_tested_at": null,
  "last_test_status": null,
  "last_test_error": null,
  "created_at": 1790000000000000,
  "updated_at": 1790000000000000
}

A connector stores the credentials and transport settings of one notification provider for an organization. Listing and reading connectors requires alerts.read. Creating, updating, testing, and deleting a connector requires alerts.manage.

Operation	Endpoint
List connector types	`GET /api/v1/notify/connector-types`
List connectors	`GET /api/v1/notify/connectors`
Create a connector	`POST /api/v1/notify/connectors`
Get a connector	`GET /api/v1/notify/connectors/{id}`
Update a connector	`PUT /api/v1/notify/connectors/{id}`
Test a connector	`POST /api/v1/notify/connectors/{id}/test`
Delete a connector	`DELETE /api/v1/notify/connectors/{id}`

Connector types

The type list returns connector_type and the capabilities of every type that the running backend registers. The types are email_smtp, lark_app, lark_webhook, slack_app, slack_webhook, and webhook.

[
  {
    "connector_type": "slack_webhook",
    "capabilities": {
      "direct_user": false,
      "group": true,
      "rich_text": true,
      "interactive": false,
      "acknowledgement": false,
      "attachments": false
    }
  }
]

The config object of a connector depends on its type. Every timeout_secs defaults to 10 and accepts 1 through 60. URLs must be absolute http or https URLs.

`connector_type`	`config` keys
`email_smtp`	`host` and `from` (required), `port` (default `587`), `username`, `password`, `tls` (`none`, `starttls` by default, or `tls`), `timeout_secs`
`slack_app`	`bot_token`, `client_id` and `client_secret` (a bot token, a client ID and secret, or all three), `api_base_url` (default `https://slack.com/api`), `timeout_secs`
`slack_webhook`	`webhook_url` (required), `timeout_secs`
`lark_app`	`app_id` and `app_secret` (required), `api_base_url`, `receive_id_type` (`open_id` by default, `user_id`, `union_id`, `email`, or `chat_id`), `timeout_secs`
`lark_webhook`	`webhook_url` (required), `secret`, `timeout_secs`
`webhook`	`url` (required), `method` (`post` by default, `put`, or `patch`), `headers`, `timeout_secs`

Notification channels explains each provider and its targets.

Create a connector

POST /api/v1/notify/connectors

Field	Type	Required	Notes
`name`	string	Yes	Unique within the organization.
`connector_type`	string	Yes	One of the types above. The type cannot change later. `type` is accepted as an alias.
`config`	object	Yes	The settings of the type.
`enabled`	boolean	No	Default `true`.

curl -X POST http://localhost:5080/api/v1/notify/connectors \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '{
    "name": "Operations webhook",
    "connector_type": "webhook",
    "config": {
      "url": "https://hooks.example.com/molesignal",
      "method": "post",
      "headers": { "Authorization": "Bearer <token>" },
      "timeout_secs": 5
    }
  }'

{
  "id": "3KEDlokKjNmves95sRzL8tXpflY",
  "organization_id": "<organization-id>",
  "name": "Operations webhook",
  "connector_type": "webhook",
  "config": {
    "url": "***",
    "method": "post",
    "headers": "***",
    "timeout_secs": 5
  },
  "capabilities": {
    "direct_user": true,
    "group": true,
    "rich_text": true,
    "interactive": false,
    "acknowledgement": false,
    "attachments": false
  },
  "enabled": true,
  "status": "unknown",
  "last_tested_at": null,
  "last_test_status": null,
  "last_test_error": null,
  "created_at": 1790000000000000,
  "updated_at": 1790000000000000
}

MoleSignal encrypts the whole config at rest. Responses replace the value of every key that holds a credential with ***. These keys are url, webhook_url, headers, and every key that ends in password, secret, or token. Other keys, such as host, from, and timeout_secs, stay readable. status is unknown until the first test, then connected or error. last_test_status is success or failed. Routing skips a connector with the status error until a later test succeeds.

List and get connectors

GET /api/v1/notify/connectors
GET /api/v1/notify/connectors/{id}

The list returns an array of connectors in the shape above. An unknown id answers 404.

Update a connector

PUT /api/v1/notify/connectors/{id}

Field	Type	Required	Notes
`name`	string	Yes	The new name.
`config`	object	No	The new settings. Omit it to keep the stored configuration.
`enabled`	boolean	No	Default `true`. An omitted value enables the connector.

Send *** for a masked key to keep the stored secret, or send a new plaintext value to replace it:

{
  "name": "Operations webhook",
  "config": {
    "url": "***",
    "method": "post",
    "headers": "***",
    "timeout_secs": 8
  },
  "enabled": true
}

Test a connector

POST /api/v1/notify/connectors/{id}/test

Sends one message through the connector. A disabled connector cannot run a test.

Field	Type	Required	Notes
`target_type`	string	Yes	`direct_user`, `fixed_address`, `fixed_group`, or `webhook`. Each connector type accepts a subset, for example `email_smtp` accepts `direct_user` and `fixed_address`.
`target`	string	Yes	The recipient: an address, a provider identifier, a group, or a URL, depending on `target_type`.
`message`	object	No	`title`, `text`, `markdown`, and `html`. The defaults are a generic title and text.

{
  "sent": true,
  "tested_at_micros": 1790000000000000,
  "elapsed_ms": 3,
  "provider_message_id": "req-1",
  "error": null
}

A delivery failure still answers 200, with sent set to false and the reason in error, for example unavailable: webhook request failed. The test also updates status, last_tested_at, last_test_status, and last_test_error of the connector.

Delete a connector

DELETE /api/v1/notify/connectors/{id}

A successful delete answers 204 without a body. While a user endpoint, a notification policy, a fallback route, a scheduled log inspection, a status page, or Mole Agent in IM still references the connector, the call answers 409 with

notify connector is referenced by user endpoints, policies, default routes, scheduled log inspections, status pages, or Mole Agent in IM

. Move the references first.

Errors

Status	Cause
`400`	The `config` is invalid for the type, the type is unsupported (`unsupported connector type: pagerduty`), the target does not fit the connector, or the connector is disabled.
`404`	The connector does not exist.
`409`	Another connector in the organization already uses the name, or the connector is still referenced on delete.
`422`	A field is missing or a value is invalid, for example an unknown `target_type`. The response is plain text.

Last modified on October 21, 2026

Overview

Authentication

Intake

Query

APM

RUM

Streams

Alerting

Correlation & Web

Platform & Administration

Manage notification connectors

Connector types

Create a connector

List and get connectors

Update a connector

Test a connector

Delete a connector

Errors

​Connector types

​Create a connector

​List and get connectors

​Update a connector

​Test a connector

​Delete a connector

​Errors

Connector types

Create a connector

List and get connectors

Update a connector

Test a connector

Delete a connector

Errors