Creating Notification Templates

Template System: RunReveal uses Handlebars-style templating (via Raymond) to create dynamic notifications that adapt to your detection data.

Notification Template Example

Template Syntax Guide

Basic Fields

Use fieldName syntax to insert dynamic values. Most fields are under detection for both scheduled and streaming detections.

detection.name

detection.severity

detection.resultCount

Advanced Components

🔄

Loops: Repeat content for each item in a list

📊

Tables: Display data in a structured table format

🔀

Conditionals: Show content based on conditions

Formatting

Full markdown support including:

bolditaliclistslinksimagescode blocks

Notification templates allow you to customize how alerts are formatted and delivered across different channels. Templates support conditional logic, data iteration, markdown rendering, and channel-specific formatting.

🔀

Conditional Logic

Show/hide content based on detection properties

🔄

Data Iteration

Loop through detection results and arrays

📊

Table Generation

Automatically format query results as tables

📝

Markdown Support

Rich formatting with markdown rendering

Using the Template Builder

RunReveal provides a visual template builder in the dashboard to create and manage your notification templates.

🛠️ Quick Start: Creating Your First Template

Navigate

Go to Notification Channels → Templates

Create

Click "Create Template" button

Configure

Add title & body templates

Save

Save and assign to detections

Step-by-Step Guide

Access the Template Builder

Navigate to Notification Channels in the RunReveal dashboard, then click on the Templates tab.

Path: Dashboard → Notification Channels → Templates

Create a New Template

Click the Create Template button. Give your template a descriptive name that reflects its purpose (e.g., "Critical Security Alert", "Daily Digest Summary").

critical-alertsdaily-summaryslack-security

Configure the Title Template

Enter your title template in the Title field. This appears as the email subject line or message header. Keep it concise and include key information like severity and detection name.

[{{detection.severity}}] {{detection.displayName}} - {{detection.resultCount}} results

Configure the Body Template

Enter your body template in the Body field. This is the main content of your notification. Use Handlebars syntax for dynamic content, markdown for formatting, and helpers for advanced features.

Variables

{{detection.name}}

Conditionals

{{#ifEquals...}}

Tables

{{table results}}

Preview and Test the Template

The template editor shows a Preview of how your markdown and formatting will render. Note that the preview displays your template structure with placeholder values—it does not use real detection data.

💡

Testing with Real Data: To see your template with actual detection data, use the Send Test button on your notification channel after saving the template. This sends a test notification using sample detection data to your configured destination (Slack, email, etc.).

Preview Shows

✓ Markdown rendering
✓ Template structure
✓ Formatting validation

Send Test Shows

✓ Real variable substitution
✓ Conditional logic evaluation
✓ Channel-specific formatting

Save and Assign to Detections

Click Save Template to create your template. Then assign it to detections by editing the detection and selecting your template from the Notification Template dropdown.

💡 Tip: You can also specify templates in Detection-as-Code using the notificationTemplate field.

Assigning Templates to Detections

🖱️

Via Dashboard UI

Go to Detections → Detection Queries
Edit the detection you want to customize
Find the "Notification Template" dropdown
Select your custom template
Save the detection

💻

Via Detection-as-Code

Add the template name to your detection YAML:

notificationNames:

- slack-security

# Override default template

notificationTemplate: critical-alerts

Template Structure

Templates consist of two parts:

📌 Title Template

Purpose: Short summary text

Used in email subject lines, Slack message titles, and notification headers

Keep it concise (50-100 characters)

📄 Body Template

Purpose: Full notification content

Used in email bodies, Slack message content, and detailed notifications

Can include rich formatting, tables, and links

Core Concepts

Inserting Dynamic Values

Access detection properties using dot notation. Variables are wrapped in double curly braces.

Basic Syntax

detection.displayName

Display name of the detection

detection.severity

Severity level (Critical, High, Medium, Low)

detection.riskScore

Risk score value (0-100)

detection.resultLink

URL to view full results in RunReveal

2. Conditional Logic

Conditional helpers allow you to show or hide content based on detection properties.

Comparison Helpers

Equality Checks

ifEquals - Check if values are equal
ifNotEquals - Check if values differ

Numeric Comparisons

ifGreaterThan - Greater than
ifLessThan - Less than
ifGreaterThanOrEqual - Greater or equal

String Operations

ifContains - String contains
ifStartsWith - String starts with
ifEndsWith - String ends with

Empty Checks

ifNotEmpty - Value exists
ifEmpty - Value is empty

💡 Example Use Cases

• Show critical alert banner only when severity equals "Critical"
• Display high-risk warning when risk score is greater than 80
• Show error message only when detection.error is not empty
• Customize content based on channel type (email vs Slack)

3. Data Iteration

Loop through detection results and arrays to display multiple items.

Loop Helper

Basic Loop Structure

loop- Iterate through detection.results array

item- Current item in the loop

index- Current index (0-based)

first- True if first item

last- True if last item

Common Patterns

• Loop through detection results
• Iterate over categories array
• Process MITRE techniques
• Display extracted fields

Best Practices

• Always check ifNotEmpty before looping
• Use index for numbering items
• Use first/last for special formatting
• Limit display to first N items if needed

4. Table Generation

Automatically format detection results as tables for better readability.

🔍

Auto-Detect Columns

The table helper automatically detects columns from your result data.

table detection.results

Use when you want all columns displayed

🎯

Specify Columns

Control exactly which columns appear in your table.

tableWithColumns detection.results "col1" "col2"

Use when you need specific columns only

5. Markdown Rendering

Convert markdown content to HTML for rich formatting in your notifications.

📝 Markdown Support

Use the markdownToHTML helper to render formatted content:

Supported Markdown Features

✓Bold & Italic

✓Headers

✓Lists

✓Links

✓Code blocks

✓Tables

✓Blockquotes

✓Horizontal rules

Template Organization Patterns

Pattern 1: Severity-Based Styling

Organize content based on detection severity levels.

Critical

Immediate action required

High

Review within 1 hour

Medium

Review within 24 hours

Low

Review when convenient

Use conditional logic to apply different styling and messaging based on severity level.

Pattern 2: Risk Score Visualization

Display risk scores with visual indicators.

Risk Score Ranges

80-100: Very High Risk

60-79: High Risk

40-59: Medium Risk

0-39: Low Risk

Use ifGreaterThan helpers to conditionally display risk indicators.

Pattern 3: Result Organization

Structure detection results for clarity.

Recommended Structure

1
Summary Section
Detection name, severity, risk score, result count
2
Results Table
Formatted table of detection results
3
Detailed Analysis
Loop through results for detailed view
4
Action Items
Investigation steps and quick links

Template Variables Reference

Detection Object Properties

Property	Type	Description
detection.id	string	Unique execution ID
detection.displayName	string	Human-readable detection name
detection.severity	string	Severity level (Critical, High, Medium, Low)
detection.riskScore	number	Risk score (0-100)
detection.resultCount	number	Number of results found
detection.results	array	Query results (array of objects)
detection.resultLink	string	URL to view full results
detection.categories	array	Category tags
detection.error	string	Error message if execution failed

Channel Variable

channel - The notification channel type (email, slack, discord, webhook, jira, pagerduty, linear, google-chat)

Use this variable to customize formatting for different channels.

Best Practices

✅ Do

• Keep titles concise (50-100 characters)
• Always check ifNotEmpty before iterating
• Include error handling sections
• Provide investigation steps
• Link to full results
• Test with empty results
• Use markdown for rich formatting

❌ Don't

• Assume results always exist
• Create overly long titles
• Skip error handling
• Hard-code values that should be dynamic
• Forget to test edge cases
• Use complex nested conditionals unnecessarily
• Ignore channel-specific formatting needs

Ready-to-Use Templates

📋

Copy & Paste Ready: Each template below can be copied directly into RunReveal's notification template editor. Templates demonstrate different features of the Handlebars templating system.

📝

Basic Alert Template

Variable interpolation basics

BEGINNER

VariablesMarkdown

A simple template demonstrating basic variable substitution. Use double curly braces to insert detection properties like name, severity, and risk score.

Title Template

[{{detection.severity}}] {{detection.displayName}}

Key Features

✓ Simple variable syntax
✓ Dot notation for nested properties
✓ Markdown formatting support

Title:

[{{detection.severity}}] {{detection.displayName}} - {{detection.resultCount}} results

Body:

## {{detection.displayName}}
 
**Severity:** {{detection.severity}}
**Risk Score:** {{detection.riskScore}}
**Results Found:** {{detection.resultCount}}
 
[View Full Results]({{detection.resultLink}})

🔀

Severity-Based Conditionals

Dynamic content with ifEquals

INTERMEDIATE

ifEqualsConditionalsEmoji

Use ifEquals to show different content based on severity level. Great for adding visual indicators and urgency messaging.

Output Preview

🚨 Critical

⚠️ High

📋 Medium

ℹ️ Low

Title:

{{#ifEquals detection.severity "Critical"}}🚨 CRITICAL: {{/ifEquals}}{{#ifEquals detection.severity "High"}}⚠️ HIGH: {{/ifEquals}}{{#ifEquals detection.severity "Medium"}}📋 MEDIUM: {{/ifEquals}}{{#ifEquals detection.severity "Low"}}ℹ️ LOW: {{/ifEquals}}{{detection.displayName}}

Body:

# {{detection.displayName}}
 
{{#ifEquals detection.severity "Critical"}}
> 🚨 **CRITICAL ALERT** - Immediate action required!
{{/ifEquals}}
{{#ifEquals detection.severity "High"}}
> ⚠️ **High Priority** - Review within 1 hour
{{/ifEquals}}
{{#ifEquals detection.severity "Medium"}}
> 📋 **Medium Priority** - Review within 24 hours
{{/ifEquals}}
{{#ifEquals detection.severity "Low"}}
> ℹ️ **Low Priority** - Review when convenient
{{/ifEquals}}
 
| Property | Value |
|----------|-------|
| Severity | {{detection.severity}} |
| Risk Score | {{detection.riskScore}} |
| Results | {{detection.resultCount}} |
 
[View Details]({{detection.resultLink}})

📊

Auto-Generated Tables

Display results as formatted tables

INTERMEDIATE

tabletableWithColumnsifNotEmpty

The table helper automatically formats detection results as a markdown table. Use tableWithColumns to specify which columns to display.

Auto-detect columns

table detection.results

Specific columns

tableWithColumns detection.results "user" "action"

Title:

{{detection.displayName}} ({{detection.resultCount}} matches)

Body:

## {{detection.displayName}}
 
**{{detection.resultCount}}** results found | **Risk Score:** {{detection.riskScore}}
 
{{#ifNotEmpty detection.results}}
### Detection Results
 
{{table detection.results}}
{{/ifNotEmpty}}
 
{{#ifEmpty detection.results}}
_No results to display._
{{/ifEmpty}}
 
[Open in RunReveal]({{detection.resultLink}})

🔄

Loop Through Results

Iterate with each helper

ADVANCED

each@index@keythis

Use #each to iterate through arrays. Access the current item with this, index with @index, and object keys with @key.

Loop Variables

this

Current item

@index

Position (0-based)

@first

Is first item

@last

Is last item

Title:

{{detection.displayName}} - {{detection.resultCount}} events detected

Body:

# {{detection.displayName}}
 
{{detection.resultCount}} events require your attention.
 
{{#ifNotEmpty detection.results}}
## Event Details
 
{{#each detection.results}}
### Event {{@index}}
{{#each this}}
- **{{@key}}**: {{this}}
{{/each}}
 
---
{{/each}}
{{/ifNotEmpty}}
 
{{#ifEmpty detection.results}}
_No events to display._
{{/ifEmpty}}
 
[View Full Analysis]({{detection.resultLink}})

📈

Risk Score Thresholds

Numeric comparisons with ifGreaterThan

ADVANCED

ifGreaterThanifLessThanNested Conditionals

Use numeric comparison helpers to create threshold-based messaging. Combine ifGreaterThan and ifLessThan for range checks.

0-60
Low Risk

61-80
Elevated

81-100
High Risk

Title:

{{#ifGreaterThan detection.riskScore 80}}🔴{{/ifGreaterThan}}{{#ifGreaterThan detection.riskScore 60}}{{#ifLessThan detection.riskScore 81}}🟠{{/ifLessThan}}{{/ifGreaterThan}}{{#ifLessThan detection.riskScore 61}}🟢{{/ifLessThan}} {{detection.displayName}}

Body:

## {{detection.displayName}}
 
{{#ifGreaterThan detection.riskScore 80}}
### 🔴 Very High Risk ({{detection.riskScore}}/100)
This detection requires immediate attention.
{{/ifGreaterThan}}
 
{{#ifGreaterThan detection.riskScore 60}}
{{#ifLessThan detection.riskScore 81}}
### 🟠 Elevated Risk ({{detection.riskScore}}/100)
This detection should be reviewed soon.
{{/ifLessThan}}
{{/ifGreaterThan}}
 
{{#ifLessThan detection.riskScore 61}}
### 🟢 Normal Risk ({{detection.riskScore}}/100)
This detection has a normal risk level.
{{/ifLessThan}}
 
**Results Found:** {{detection.resultCount}}
 
[Investigate Now]({{detection.resultLink}})

📱

Channel-Specific Formatting

Customize output per notification channel

ADVANCED

channelifEquals

The channel variable indicates the notification destination. Use it to format messages appropriately for each platform.

💬

slack

📧

🎮

discord

🔗

webhook

Title:

{{detection.displayName}}

Body:

{{#ifEquals channel "slack"}}
*{{detection.displayName}}*
Severity: `{{detection.severity}}` | Risk: `{{detection.riskScore}}`
Results: {{detection.resultCount}}
<{{detection.resultLink}}|View in RunReveal>
{{/ifEquals}}
 
{{#ifEquals channel "email"}}
# {{detection.displayName}}
 
| Property | Value |
|----------|-------|
| Severity | {{detection.severity}} |
| Risk Score | {{detection.riskScore}} |
| Results | {{detection.resultCount}} |
 
[View Full Results]({{detection.resultLink}})
{{/ifEquals}}
 
{{#ifEquals channel "discord"}}
**{{detection.displayName}}**
> Severity: {{detection.severity}}
> Risk Score: {{detection.riskScore}}
> Results: {{detection.resultCount}}
 
{{detection.resultLink}}
{{/ifEquals}}
 
{{#ifEquals channel "webhook"}}
Detection: {{detection.displayName}}
Severity: {{detection.severity}}
Risk: {{detection.riskScore}}
Count: {{detection.resultCount}}
Link: {{detection.resultLink}}
{{/ifEquals}}

🛡️

Error Handling

Gracefully handle detection failures

BEST PRACTICE

ifNotEmptyifEmptydetection.error

Always check for errors using ifNotEmpty detection.error. This ensures users are notified when detections fail and provides clear troubleshooting guidance.

❌Error State

Shows error message and troubleshooting steps

✅Success State

Shows normal detection results

Title:

{{#ifNotEmpty detection.error}}❌ Error: {{/ifNotEmpty}}{{detection.displayName}}

Body:

## {{detection.displayName}}
 
{{#ifNotEmpty detection.error}}
### ❌ Detection Error
 
An error occurred while running this detection:
 
> {{detection.error}}
 
Please review the detection configuration and try again.
{{/ifNotEmpty}}
 
{{#ifEmpty detection.error}}
### ✅ Detection Successful
 
**Severity:** {{detection.severity}}
**Risk Score:** {{detection.riskScore}}
**Results Found:** {{detection.resultCount}}
 
{{#ifNotEmpty detection.results}}
{{table detection.results}}
{{/ifNotEmpty}}
 
[View Results]({{detection.resultLink}})
{{/ifEmpty}}

Testing Your Templates

Test Scenarios

Data Variations

• Empty results (resultCount = 0)
• Single result
• Multiple results (10+)
• Missing optional fields

Severity & Risk

• High risk scores (above 80)
• Low risk scores (below 20)
• Different severity levels
• Error conditions

Notification Channels - Configure and manage notification channels
Detections - Create and manage detection rules
Writing Detections - Learn how to write effective detections
Detection as Code - Manage detections with version control

📌 Title Template

📄 Body Template

Basic Syntax

Comparison Helpers

Equality Checks

Numeric Comparisons

String Operations

Empty Checks

💡 Example Use Cases

Loop Helper

Basic Loop Structure

Common Patterns

Best Practices

Auto-Detect Columns

Specify Columns

📝 Markdown Support

Supported Markdown Features

Risk Score Ranges

Recommended Structure

✅ Do

❌ Don't

Test Scenarios

Data Variations

Severity & Risk

On this page