Back to Widget

Webhook Notifications

Ting Reader can proactively send notifications to external services when events such as login, playback, ingestion, and scanning occur. Each webhook can be independently configured with request headers and a Body template, so it can connect to WeCom as well as self-hosted ntfy, Gotify, or automation services.

Per-event Push

Each target can individually select login, playback, media library changes, work changes, and scan completion events.

Custom Requests

Both request headers and the Body can use variables, and JSON templates support auto-escaping.

Test Before Saving

Test sends display the HTTP status, service response, and the final request body, making troubleshooting more straightforward.

1. Create a Notification Target

Administrators go to Me - Settings & Management - Notifications & Eventsand click “Add Webhook”. After filling in the name and URL, you can choose a service from common templates or fully edit it yourself.

Built-in Templates

WeCom Markdown, WeCom Text, ntfy JSON, Gotify JSON, Raw Event JSON, and Plain Text.

2. Template Variables

Plain variables are output as-is, suitable for plain text; for JSON request bodies, use{{json:变量}}, which automatically handles quotes and line breaks.

Output as-is

{{title}}
{{message}}
{{event}}
{{notification}}
{{data.username}}

JSON-safe Output

{
  "title": {{json:title}},
  "message": {{json:message}},
  "event": {{json:event}}
}

{{notification}}is “title + newline + body”, and{{json:payload}} outputs the complete raw event.

3. Common Service Configurations

WeCom Bot

Use the full address provided by the group bot for the URL; the bot key is already included in the URL’skey parameter.

https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=机器人密钥
{
  "msgtype": "markdown",
  "markdown": {
    "content": {{json:notification}}
  }
}

Ting Reader further checks the errcode in the WeCom response to avoid cases where HTTP 200 is returned but the message actually failed to send.

ntfy

In JSON publishing mode, fill in the service root address and put the Topic in the request body. For private services, you can add anAuthorization request header.

https://ntfy.example.com
{
  "topic": "ting-reader",
  "title": {{json:title}},
  "message": {{json:message}},
  "priority": 3,
  "tags": ["headphones"]
}

Gotify

Use the Gotify Application Token and place it in the message API URL.

https://gotify.example.com/message?token=APPLICATION_TOKEN
{
  "title": {{json:title}},
  "message": {{json:message}},
  "priority": 5
}

4. Custom Request Headers

Request headers can be used for Bearer Tokens, Basic Auth, or custom parameters of the target service. Values also support template variables.

Content-Type: application/json
Authorization: Bearer your-token
X-Event: {{event}}

Authentication tokens are sent with the request. Use HTTPS and avoid publishing full tokens in logs or screenshots.

5. Listenable Events

user.login

User Login

Triggered when a user logs in successfully.

playback.play

Playback Start

Triggered when a user starts playing a work or chapter.

library.scan_completed

Scan Completed

Triggered when a media library scan task finishes.

book.created

Work Added

Triggered when a new work is created or scanned into the library.

6. Testing & Troubleshooting

  • Test the send before saving the configuration.
  • Expand “Actual Request Body” to inspect the rendered template result.
  • For JSON string values, prefer {{json:变量}}.
  • In ntfy JSON mode, fill in the service root address and put the Topic in the Body.
  • Use the Application Token for Gotify, not the Client Token.
  • In Docker, 127.0.0.1 points to the Ting Reader container itself.
  • Sending records can be viewed in “Notification Records” under system logs.
← PreviousWidgetNext →Plugin Development