Docs › Integrations › Webhooks

Webhooks

Any system that can make an HTTP POST request can send events to NotiLens — no SDK required.

Overview

NotiLens Webhooks

Webhooks allow any app, system, or script to send events directly to NotiLens. When an event occurs, NotiLens receives it instantly and notifies you based on your configured rules and priorities.

Works with servers, custom apps, automation scripts, AI agents, IoT devices, or third-party platforms.

Setup

How to Set Up a NotiLens Webhook

1. Create a Topic

  1. Open the NotiLens app and select Custom Integration.
  2. Set a Topic Name and description for your system or app.
  3. Copy the generated Webhook URL.
https://hook.notilens.com/webhook/<TOPIC_ID>/send

2. Send Events

  1. Trigger an HTTP POST request when an event occurs.
  2. Use the NotiLens webhook URL as the endpoint.
  3. Send event details in JSON format.
Sample JSON payload:

{
  "title": "Server Alert",
  "message": "CPU usage exceeded 80% for more than 5 minutes.",
  "type": "urgent",
  "event": "cpu_high",
  "image_url": "https://example.com/images/alert.png",
  "open_url": "https://dashboard.example.com/servers/123",
  "download_url": "https://dashboard.example.com/servers/log.pdf",
  "tags": "AWS_inst_id, prod",
  "meta": {
    "server_id": "srv_123",
    "threshold": 80,
    "current_usage": 92.5
  },
  "is_actionable": true,
  "force_send": true
}

Events can come from backend services, automation scripts, AI agents, or any system capable of sending HTTP requests.

3. Configure a Secret Key

  1. A secret key is generated for each topic by default.
  2. Include it in your request headers: X-NOTILENS-KEY: <YOUR_SECRET_KEY>
  3. This ensures that only trusted sources can send events to your topic.

Secret key validation can be disabled but it is not recommended.

Payload

Webhook Payload Format

Send a POST request with JSON data. Only title and message are required.

Key Required Type Description
title Yes string Short notification heading
message Yes string Main content of the notification
type No string Notification category: info, success, warning, important, urgent
event No string Logical event identifier, e.g., cpu_high, payment_failed
image_url No string (URL) Image to display in notification
open_url No string (URL) URL to open when notification is clicked
download_url No string (URL) Download file when clicked
tags No string Comma-separated tags for classification
meta No JSON Additional structured data for reference
is_actionable No boolean If true, repeated notifications continue until acknowledged
force_send No boolean If true, the notification bypasses ML-based filtering and is delivered immediately.
Example

Send Notification to NotiLens

curl -X POST "https://hook.notilens.com/webhook/TOPIC_ID/send" \
  -H "Content-Type: application/json" \
  -H "X-NOTILENS-KEY: YOUR_SECRET_KEY" \
  -d '{
    "title": "Server Alert",
    "message": "CPU usage exceeded 80% for more than 5 minutes.",
    "type": "urgent",
    "event": "cpu_high",
    "image_url": "https://example.com/images/alert.png",
    "open_url": "https://dashboard.example.com/servers/123",
    "download_url": "https://dashboard.example.com/servers/log.pdf",
    "tags": "AWS_inst_id, prod",
    "meta": {
      "server_id": "srv_123",
      "threshold": 80,
      "current_usage": 92.5
    },
    "is_actionable": true,
    "force_send": true
  }'
Events

Sample Events

Event Description Use Case
cpu_high Server CPU usage exceeded threshold System monitoring
order.failed Payment or order processing failed E-commerce alerts
automation.stopped An automated workflow stopped unexpectedly Workflow monitoring
iot.offline Smart device went offline IoT monitoring
← Previous SDK & CLI