> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook notification connectors

> Configure Slack, Lark, and generic webhook delivery with target overrides, signing, and encrypted credentials.

MoleSignal currently provides three webhook connector types: Slack webhook, Lark webhook, and a
generic JSON webhook. Create webhook connectors under **Settings → Notify management → Connectors**.

Read [Notification channels and delivery](/en-US/notification-channels) first for identity binding,
policy creation, fallback routes, or delivery history.

## Compare webhook types

| Connector       | Request format                         | Authentication                        | Target types             |
| --------------- | -------------------------------------- | ------------------------------------- | ------------------------ |
| `slack_webhook` | `{ "text": "..." }`                    | Credential in webhook URL             | `fixed_group`, `webhook` |
| `lark_webhook`  | Lark `msg_type: text`                  | Credential in URL, optional signature | `fixed_group`, `webhook` |
| `webhook`       | MoleSignal target and message envelope | Custom JSON headers                   | All target types         |

For `fixed_group`, the connector sends to the configured URL. For `webhook`, the target value must
be an absolute URL and overrides the configured URL for that delivery.

## Slack webhook

Configure an incoming webhook URL and a timeout from 1 to 60 seconds:

```json theme={null}
{
  "webhook_url": "https://hooks.slack.com/services/T000/B000/secret",
  "timeout_secs": 10
}
```

MoleSignal joins the message title and Markdown body and sends:

```json theme={null}
{
  "text": "[Critical] Checkout error rate is high\nThe error rate exceeded 5%."
}
```

A 2xx HTTP response is successful. Any other response or timeout marks the delivery as failed.

## Lark webhook

Configure a Lark or Feishu custom bot URL. Add the bot signing secret only when signature
verification is enabled:

```json theme={null}
{
  "webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx",
  "secret": "replace-with-signing-secret",
  "timeout_secs": 10
}
```

Without a signing secret, MoleSignal sends:

```json theme={null}
{
  "msg_type": "text",
  "content": {
    "text": "[Critical] Checkout error rate is high\nThe error rate exceeded 5%."
  }
}
```

With a signing secret, MoleSignal generates a Unix timestamp in seconds, builds
`timestamp + "\n" + secret`, uses that value as the HMAC-SHA256 key for an empty message, and
Base64-encodes the digest. The request includes both fields:

```json theme={null}
{
  "timestamp": "1599360473",
  "sign": "base64-signature",
  "msg_type": "text",
  "content": {
    "text": "[Critical] Checkout error rate is high\nThe error rate exceeded 5%."
  }
}
```

MoleSignal requires both a successful HTTP status and a zero `code` or `status_code` in the Lark
response.

<Note>
  Keep the MoleSignal server clock synchronized. Lark rejects stale signed requests.
</Note>

## Generic webhook

Configure the default URL, method, headers, and timeout:

```json theme={null}
{
  "url": "https://notify.example.com/molesignal",
  "method": "post",
  "headers": {
    "Authorization": "Bearer <token>",
    "X-Environment": "production"
  },
  "timeout_secs": 10
}
```

The method can be `post`, `put`, or `patch`. Header names and values must be valid HTTP headers.
MoleSignal sends this envelope:

```json theme={null}
{
  "target": {
    "type": "fixed_group",
    "value": "platform-oncall",
    "metadata": {}
  },
  "message": {
    "title": "Checkout error rate is high",
    "text": "The error rate exceeded 5%.",
    "markdown": "**Checkout** error rate exceeded 5%.",
    "html": null,
    "metadata": {}
  }
}
```

Any 2xx response is successful. If the response includes `X-Request-ID`, MoleSignal records the
header value as the provider message ID.

## Create and test over the API

Create a generic webhook connector:

```bash theme={null}
curl -X POST "$MOLESIGNAL_URL/api/v1/notify/connectors" \
  -H "Authorization: Bearer $MS_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "platform webhook",
    "connector_type": "webhook",
    "enabled": true,
    "config": {
      "url": "https://notify.example.com/molesignal",
      "method": "post",
      "headers": {"Authorization": "Bearer <token>"},
      "timeout_secs": 10
    }
  }'
```

Save the returned connector `id`, then send a test:

```bash theme={null}
curl -X POST "$MOLESIGNAL_URL/api/v1/notify/connectors/$CONNECTOR_ID/test" \
  -H "Authorization: Bearer $MS_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type": "fixed_group",
    "target": "platform-oncall",
    "message": {
      "title": "MoleSignal connector test",
      "text": "Webhook delivery is working."
    }
  }'
```

Listing, reading, creating, and updating connectors returns sensitive config fields as `***`.
During an existing connector update, send the unchanged `***` value to preserve the stored secret.

## Security and limitations

* MoleSignal encrypts the complete connector configuration at rest.
* API responses mask `url`, `webhook_url`, `headers`, `secret`, tokens, and passwords.
* Treat a webhook URL as a credential even when no additional secret is configured.
* Prefer `https`; use `http` only on a trusted network.
* Restrict outbound access from MoleSignal to required connector destinations.
* A disabled connector cannot send tests or notifications.

<Warning>
  The current connector registry does not include native DingTalk or WeCom adapters. Use a generic
  webhook only when the target accepts the MoleSignal envelope, or place a transformation relay in
  front of the provider endpoint.
</Warning>