Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/content/shared/influxdb3-plugins/plugins-library/official/notifier.md

8.8 KiB
Raw Permalink Blame History

The Notifier Plugin provides multi-channel notification capabilities for {{% product-name %}}, enabling real-time alert delivery through various communication channels. Send notifications via Slack, Discord, HTTP webhooks, SMS, or WhatsApp based on incoming HTTP requests. Acts as a centralized notification dispatcher that receives data from other plugins or external systems and routes notifications to the appropriate channels.

Configuration

This HTTP plugin receives all configuration via the request body. No trigger arguments are required.

Plugin metadata

This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the InfluxDB 3 Explorer UI to display and configure the plugin.

Request body parameters

Send these parameters as JSON in the HTTP POST request body:

Parameter Type Default Description
notification_text string required Text content of the notification message
senders_config object required Configuration for each notification channel

Sender-specific configuration (in request body)

The senders_config object accepts channel configurations where keys are sender names and values contain channel-specific settings:

Slack notifications

Parameter Type Default Description
slack_webhook_url string required Slack webhook URL
slack_headers string none Base64-encoded JSON headers

Discord notifications

Parameter Type Default Description
discord_webhook_url string required Discord webhook URL
discord_headers string none Base64-encoded JSON headers

HTTP webhook notifications

Parameter Type Default Description
http_webhook_url string required Custom webhook URL for HTTP POST
http_headers string none Base64-encoded JSON headers

SMS notifications (via Twilio)

Parameter Type Default Description
twilio_sid string required Twilio Account SID (or use TWILIO_SID env var)
twilio_token string required Twilio Auth Token (or use TWILIO_TOKEN env var)
twilio_from_number string required Sender phone number in E.164 format
twilio_to_number string required Recipient phone number in E.164 format

WhatsApp notifications (via Twilio)

Parameter Type Default Description
twilio_sid string required Twilio Account SID (or use TWILIO_SID env var)
twilio_token string required Twilio Auth Token (or use TWILIO_TOKEN env var)
twilio_from_number string required Sender WhatsApp number in E.164 format
twilio_to_number string required Recipient WhatsApp number in E.164 format

Software Requirements

  • {{% product-name %}}: with the Processing Engine enabled.
  • Python packages:
    • httpx (for HTTP requests)
    • twilio (for SMS/WhatsApp notifications)

Installation steps

  1. Start {{% product-name %}} with the Processing Engine enabled (--plugin-dir /path/to/plugins):

    influxdb3 serve \
  --node-id node0 \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --plugin-dir ~/.plugins

  2. Install required Python packages:

    influxdb3 install package httpx
influxdb3 install package twilio

Trigger setup

HTTP trigger

Create an HTTP trigger to handle notification requests:

influxdb3 create trigger \
  --database mydb \
  --path "gh:influxdata/notifier/notifier_plugin.py" \
  --trigger-spec "request:notify" \
  notification_trigger

This registers an HTTP endpoint at /api/v3/engine/notify.

Enable trigger

influxdb3 enable trigger --database mydb notification_trigger

Example usage

Example 1: Slack notification

Send a notification to Slack:

curl -X POST http://localhost:8181/api/v3/engine/notify \
  -H "Authorization: Bearer $INFLUXDB3_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_text": "Alert: High CPU usage detected on server1",
    "senders_config": {
      "slack": {
        "slack_webhook_url": "'"$SLACK_WEBHOOK_URL"'"
      }
    }
  }'

Set INFLUXDB3_AUTH_TOKEN and SLACK_WEBHOOK_URL to your credentials.

Expected output

Notification sent to Slack channel with message: "Alert: High CPU usage detected on server1"

Example 2: SMS notification

Send an SMS via Twilio:

curl -X POST http://localhost:8181/api/v3/engine/notify \
  -H "Authorization: Bearer $INFLUXDB3_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_text": "Critical alert: System down",
    "senders_config": {
      "sms": {
        "twilio_from_number": "'"$TWILIO_FROM_NUMBER"'",
        "twilio_to_number": "'"$TWILIO_TO_NUMBER"'"
      }
    }
  }'

Set TWILIO_FROM_NUMBER and TWILIO_TO_NUMBER to your phone numbers. Twilio credentials can be set via TWILIO_SID and TWILIO_TOKEN environment variables.

Example 3: Multi-channel notification

Send notifications via multiple channels simultaneously:

curl -X POST http://localhost:8181/api/v3/engine/notify \
  -H "Authorization: Bearer $INFLUXDB3_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_text": "Performance warning: Memory usage above threshold",
    "senders_config": {
      "slack": {
        "slack_webhook_url": "'"$SLACK_WEBHOOK_URL"'"
      },
      "discord": {
        "discord_webhook_url": "'"$DISCORD_WEBHOOK_URL"'"
      }
    }
  }'

Set SLACK_WEBHOOK_URL and DISCORD_WEBHOOK_URL to your webhook URLs.

Code overview

Files

  • notifier_plugin.py: The main plugin code containing the HTTP handler for notification dispatch

Logging

Logs are stored in the trigger's database in the system.processing_engine_logs table. To view logs:

influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'notification_trigger'"

Main functions

process_http_request(influxdb3_local, request_body, args)

Handles incoming HTTP notification requests. Parses the request body, extracts notification text and sender configurations, and dispatches notifications to configured channels.

Key operations:

  1. Validates request body for required notification_text and senders_config
  2. Iterates through sender configurations (Slack, Discord, HTTP, SMS, WhatsApp)
  3. Dispatches notifications with built-in retry logic and error handling
  4. Returns success/failure status for each channel

Troubleshooting

Common issues

Issue: Notification not delivered

Solution: Verify webhook URLs are correct and accessible. Check Twilio credentials and phone number formats. Review logs for specific error messages.

Issue: Authentication errors

Solution: Ensure Twilio credentials are set via environment variables or request parameters. Verify webhook URLs have proper authentication if required.

Issue: Rate limiting

Solution: Plugin includes built-in retry logic with exponential backoff. Consider implementing client-side rate limiting for high-frequency notifications.

Environment variables

For security, set Twilio credentials as environment variables:

export TWILIO_SID=your_account_sid
export TWILIO_TOKEN=your_auth_token

Viewing logs

Check processing logs in the InfluxDB system tables:

influxdb3 query --database YOUR_DATABASE "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%notifier%' ORDER BY event_time DESC LIMIT 10"

Report an issue

For plugin issues, see the Plugins repository issues page.

Find support for {{% product-name %}}

The InfluxDB Discord server is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the Support and feedback options.