dsh-webhook-notifier

Readme

# dsh-webhook-notifier

> DSH event-notification plugin: send HTTP notifications to a webhook when specified events occur.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
**English** · [中文](README.zh.md)

**Can be used together with the [Desktop Pet](https://github.com/masknull/dsh-pet-standalone) project** — e.g. push a notification to your desktop pet when a turn completes.

## Features

- 🔔 **5 trigger scenarios** (each independently toggleable in settings):
  - AI turn completed
  - Approval requested (approval)
  - AI asks a question
  - AI errored
  - AI started running
- 🌐 **HTTP requests**: `GET` / `POST`, body as `JSON` / `Form`
- 📦 **Two payload modes**:
  - **Preset fields**: toggle fields and write templates (e.g. `{"session":"{{sessionName}}"}`)
  - **Custom text**: always sent as the `msg` parameter, free-form content
- 🏷️ **Always sends `type` + `type_cn`**: the message kind in English and Chinese
- 🔧 **Custom headers**: add arbitrary header key/value pairs
- 🔍 **Test send**: verify connectivity with one click
- 📜 **Send log**: each entry expandable to inspect full request content, response, and errors
- 💾 **Persistent config**: stored in `$DSH_HOME/settings.yaml`, survives restarts

## Install

```bash
dsh plugin --profile web add github:masknull/dsh-webhook-notifier
```

**Restart `dsh web`** after installing.

## Usage

1. Open **Settings → Webhook Notifier**
2. Turn on the **Webhook 通知** switch
3. Configure **Request**: method, URL, payload mode, headers
4. Tick the **trigger scenarios** (which events send notifications)
5. Fill the payload in **Preset Fields** or **Custom Text**
6. Click **Test Send** to verify, then **Save**

## Placeholders

Templates support the following placeholders (`{{ }}` wrapped, distinct from JSON `{}`):

| Placeholder | Description |
|-------------|-------------|
| `{{type}}` | Message type, always sent (e.g. `turnComplete`) |
| `{{type_cn}}` | Message type in Chinese, always sent (e.g. `回合完成`) |
| `{{sessionId}}` | Session ID |
| `{{sessionName}}` | Session title |
| `{{turn}}` | Turn number |
| `{{time}}` | Current time (UTC+8) |
| `{{trigger}}` | Trigger scenario |
| `{{toolName}}` | Tool name (approval requests) |
| `{{reason}}` | Reason (approval requests) |
| `{{error}}` | Error message (AI errored) |
| `{{question}}` | Question text (AI asks) |
| `{{status}}` | Status (agent running) |
| `{{userMessage}}` | Latest user message |
| `{{assistantMessage}}` | Latest AI reply |
| `{{createdAt}}` | Session creation time |

## Send Examples

**POST + JSON (preset fields):**
```json
{"type":"turnComplete","type_cn":"回合完成","sessionId":"s1","sessionName":"测试会话"}
```

**POST + JSON (custom text → `msg`):**
```json
{"msg":"任务【测试会话】回合完成","type":"turnComplete","type_cn":"回合完成"}
```

**GET:** `https://example.com/hook?type=turnComplete&type_cn=回合完成&sessionId=s1`

## Companion Projects

- [Desktop Pet](https://github.com/masknull/dsh-pet-standalone): surface notifications on your desktop pet to monitor DSH activity in real time.

## Uninstall

```bash
dsh plugin --profile web remove dsh-webhook-notifier
```

Restart `dsh web`. Config remains in `settings.yaml` (remove the fields manually to fully purge).

## License

[MIT](LICENSE)