Webhooks

Overview

Outgoing webhooks send an HTTP POST request to a URL you configure when a specific event occurs in DFIRe. Use them for notifications, alerting, and automated response in external systems — SIEMs, ticketing tools, paging services, or custom automation.

Webhook Secrets let you store sensitive values like API keys and reference them in webhook payloads.

Webhook configuration is found in Settings > Webhooks. The page has two tabs: Webhooks (for the webhooks themselves) and Secrets (for stored credentials).

Outgoing Webhooks

Outgoing webhooks send HTTP POST requests to a configured URL when specific events occur in DFIRe. Use them to integrate with notification services (Pushover, PagerDuty), ticketing systems (Jira, ServiceNow), SIEMs, or custom automation.

Creating an Outgoing Webhook

1. Click "Add Webhook" in the Outgoing Webhooks section
2. Configure basic settings
   • Name: Descriptive name for the webhook
   • Endpoint URL: The URL to receive webhook payloads
   • Description: Optional description of what this webhook does
3. Select trigger events

   Choose which events should trigger this webhook.

4. Optionally set a content filter

   Restrict which events fire the webhook by trigger tag (for runbook and automation events) or by timeline content. See Trigger tags.

5. Configure authentication
6. Customize the payload template
7. Save the webhook

Trigger Events

Select one or more events that should trigger the webhook:

Event	Description
Incident Created	A new incident case was created
Investigation Created	A new investigation case was created
Case Closed	A case was closed
Case Archived	A case was archived
Case Reopened	A closed case was reopened
Investigation Escalated to Incident	An investigation was escalated to incident mode
Severity/Priority Escalated	Case severity was increased (e.g., medium to high)
Severity/Priority Downgraded	Case severity was decreased
Incident Phase Changed	Incident moved to a different response phase
Timeline Event Created	A new timeline event was added to a case
Evidence Added	New evidence item was added to a case
Evidence Status Changed	Evidence item's investigation step changed
Timer at 50% (Half Time Warning)	Compliance timer reached 50% of its duration
Timer at 25% (Quarter Time Warning)	Compliance timer reached 75% elapsed (25% remaining)
Timer at 10% (Critical Warning)	Compliance timer reached 90% elapsed (10% remaining)
Timer Breached (Deadline Passed)	Compliance timer deadline has passed
IOC Added to Case	An indicator was associated with a case
IOC Classification Changed	An indicator's classification was changed (e.g., unknown to malicious)
IOC Classified Malicious	An indicator was classified as malicious
IOC Classified Suspicious	An indicator was classified as suspicious
IOC Classified Benign	An indicator was classified as benign
IOC Published	An indicator was published to TAXII/MISP feeds
IOC Unpublished	A published indicator was unpublished
IOC Revoked	An indicator was revoked (no longer considered valid)
IOC Unrevoked	A revoked indicator was restored
Runbook Step Completed	A runbook step with a webhook trigger tag was marked complete. Filter by its trigger tag with the content filter.
Automation Rule Triggered	An automation rule's "Fire a webhook" action matched. Filter by its trigger tag with the content filter.
Test Event (Manual Testing)	Used for testing webhook configuration

Trigger tags and the content filter

Some events carry a trigger tag — a short identifier that lets a single event type fan out to different webhooks. Three features in DFIRe emit tagged events:

• IOC triggers — custom response buttons on IOC Intelligence pages, defined under Settings → IOC Enrichment. Each one appears in the event list above as its own IOC Trigger: name entry; subscribe to the specific trigger you want. No content filter is needed — each trigger is its own event. See Configuration — Webhook Triggers.
• Runbook triggers — a tag on a runbook step. Marking the step complete fires the Runbook Step Completed event carrying that tag.
• Automation triggers — the trigger tag on an automation rule's "Fire a webhook" action. The rule fires the Automation Rule Triggered event carrying that tag.

For the Runbook Step Completed and Automation Rule Triggered events, the content filter is a regex matched against the trigger tag. Leave it empty to fire on every tag, or set a specific tag — or a pattern such as account_disabled|notify_soc — to choose which ones reach this webhook. Because both events filter on the same kind of tag, one webhook can serve several rules, or be shared by a runbook step and an automation rule that carry the same tag.

For Timeline Event Created, the content filter instead matches the event's subject and details — for example, @page fires the webhook only for timeline entries containing "@page".

Authentication

DFIRe supports four authentication methods for outgoing webhooks:

Method	Description
None	No authentication. Use when the endpoint doesn't require auth or when credentials are in the payload.
Basic Auth	HTTP Basic Authentication. Provide username and password.
Bearer Token	Sends an Authorization: Bearer <token> header. Provide the token value.
Custom Headers	Add custom HTTP headers. Useful for API keys sent in headers (e.g., X-API-Key). Header values are stored encrypted and are write-only — they are not shown again after saving, so re-enter them if you edit the webhook.

Payload Templates

Customize the JSON payload sent to your endpoint using template variables. If you leave the payload template empty, DFIRe sends a default payload structure.

Template Variable Syntax

Use double curly braces to insert variable values:

• {{category.variable}} - Insert the raw value
• {{category.variable|mapped}} - Apply value mappings before inserting

Available Variables

Variables are organized by category:

META.* (Request Metadata)

meta.event_type	The event that triggered this webhook
meta.timestamp	When the event occurred (ISO 8601)
meta.webhook_name	Name of this webhook configuration
meta.base_url	DFIRe instance base URL
meta.case_url	Direct URL to the case
meta.item_url	Direct URL to the evidence item (if applicable)
meta.tenant_name	Organization name
meta.tenant_uuid	Tenant identifier
meta.environment	Environment (production, development)
meta.previous_severity	Previous severity (for escalation events)
meta.new_severity	New severity (for escalation events)

CASE.* (Case Information)

case.id	Case UUID
case.case_number	Case number (e.g., CASE-2026-001)
case.title	Case title
case.description	Case description
case.status	Case status (open, closed, archived)
case.severity	Severity level (info, low, medium, high, critical)
case.case_mode	Case mode (investigation, incident)
case.phase_name	Current incident phase name
case.phase_order	Current incident phase order
case.case_type_name	Case type name
case.lead_investigator	Lead investigator username
case.created_at	Case creation timestamp
case.updated_at	Last update timestamp

EVENT.* (Timeline Event Information)

event.id	Event UUID
event.event_type	Event type (MANUAL, AUTO, etc.)
event.title	Event title/subject
event.description	Event description
event.subject	Event subject
event.details	Event details
event.location	Location information
event.is_manual	Whether this is a manual entry
event.actor_username	User who created the event
event.event_datetime	When the event occurred
event.created_at	When the event was recorded
event.metadata	Additional event metadata (JSON)

ITEM.* (Evidence Item Information)

item.uuid	Evidence item UUID
item.name	Evidence item name
item.item_type_name	Evidence type name
item.status_name	Current investigation step
item.created_at	When the item was added

INDICATOR.* (IOC Indicator Information)

indicator.id	Indicator database ID
indicator.value	Indicator value (e.g., IP address, domain, hash)
indicator.type	STIX type (e.g., ipv4-addr, domain-name, file)
indicator.classification	Classification (unknown, benign, suspicious, malicious)
indicator.confidence	Confidence level (low, medium, high)
indicator.tlp	TLP marking (clear, green, amber, amber_strict, red)
indicator.old_classification	Previous classification (for classification change events)
indicator.new_classification	New classification (for classification change events)

TIMER.* (Compliance Timer Information)

timer.id	Timer ID
timer.name	Timer name (e.g., "GDPR 72h")
timer.framework	Compliance framework
timer.duration_hours	Total duration in hours
timer.authority_name	Regulatory authority
timer.threshold_triggered	Which threshold was triggered (50, 25, 10, 0)
timer.time_remaining_seconds	Seconds remaining until deadline
timer.deadline	Deadline timestamp

SECRET.* (Stored Secrets)

Reference secrets stored in the Secrets tab:

• {{secret.<name>}} - Replaced with the secret value at send time

For example, {{secret.pushover_api_token}} inserts the value of a secret named "pushover_api_token".

Value Mappings

Value mappings transform field values before inserting them into the payload. This is useful when the receiving system expects different values than DFIRe uses.

Configuration

Define mappings as a JSON object where keys are field names and values are mapping dictionaries:

{
    "severity": {
        "info": -2,
        "low": -1,
        "medium": 0,
        "high": 1,
        "critical": 2
    },
    "event_type": {
        "MANUAL": "Manual timeline event",
        "AUTO": "Automatic system event"
    }
}

Usage

Use the |mapped filter to apply mappings:

• {{case.severity}} outputs: critical
• {{case.severity|mapped}} outputs: 2 (using the mapping above)

This is especially useful for integrating with services like Pushover that use numeric priority levels, or for translating DFIRe field values to match your organization's terminology.

Payload Preview

Click "Preview Payload" to see how your template will render with sample data. The preview shows the actual JSON that would be sent, with variables replaced by example values. This helps verify your template syntax and mappings before saving.

Additional Outgoing Webhook Settings

Retry Configuration

• Max Retries: Number of retry attempts for failed deliveries (default: 3)
• Timeout (Seconds): How long to wait for a response (default: 30)

HMAC Signing

Optionally configure a signing secret to allow the receiving endpoint to verify that requests came from DFIRe:

• If set, DFIRe includes an X-Webhook-Signature header with an HMAC-SHA256 signature
• The signature is computed over the request body using your secret
• Leave empty to skip signing

Verifying Signatures

# Python example
import hmac
import hashlib

def verify_signature(payload_body, signature_header, secret):
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Webhook Secrets

Store sensitive values like API keys and tokens securely, then reference them in webhook payloads.

Creating a Secret

1. Go to Settings > Webhooks > Secrets tab
2. Click Add Secret
3. Enter a name (used to reference the secret in templates)
4. Enter an optional description
5. Enter the secret value
6. Click Save

Using Secrets in Payloads

Reference secrets using the syntax {{secret.secret_name}}. The actual value is substituted when the webhook is sent:

{
    "token": "{{secret.pushover_token}}",
    "user": "{{secret.pushover_user}}",
    "message": "Case {{case.case_number}} - {{case.title}}"
}

Security

• Secret values are encrypted at rest using the CREDENTIAL_ENCRYPTION_KEY
• Values are never exposed in API responses or delivery logs
• Only the secret name and description are visible after creation
• You can update or delete secrets, but cannot view the stored value

Example: Pushover Notifications

This example shows how to send mobile push notifications via Pushover when someone adds "@page" to a timeline event.

1. Create Secrets

Store your Pushover credentials in Webhook Secrets:

• Create a secret named pushover_api_token with your Pushover application token
• Create a secret named pushover_api_user with your Pushover user key

2. Create the Webhook

• Name: Pushover on Timeline @page event
• Endpoint URL: https://api.pushover.net/1/messages.json
• Trigger Events: Timeline Event Created
• Content Filter: @page
• Authentication: None (credentials are in the payload)

3. Configure the Payload Template

{
    "token": "{{secret.pushover_api_token}}",
    "user": "{{secret.pushover_api_user}}",
    "title": "You have been paged for {{case.case_number}} {{case.title}}",
    "message": "You have been paged by {{event.actor_username}} on case {{case.case_number}}:\n\n{{event.event_type|mapped}}: {{event.title}}, {{event.description}}.\n\nYou can access the incident here: {{meta.case_url}}",
    "priority": "{{case.severity|mapped}}"
}

4. Configure Value Mappings

{
    "severity": {
        "info": -2,
        "low": -1,
        "medium": 0,
        "high": 1,
        "critical": 2
    },
    "event_type": {
        "MANUAL": "Manual timeline event"
    }
}

Now, when anyone adds a timeline event containing "@page", the on-call team receives a push notification with case details and a direct link.

Webhook Management

Testing Webhooks

Use the play button on a webhook card to send a test event. This fires the "Test Event (Manual Testing)" trigger with sample data.

Enabling/Disabling

Toggle the switch on a webhook card to enable or disable it without deleting the configuration. Disabled webhooks are not triggered.

Duplicating Webhooks

Use the copy button to duplicate a webhook configuration. This is useful for creating similar webhooks with minor variations.

Delivery History

Click on a webhook to view recent delivery attempts showing:

• Success or failure status
• HTTP response code
• Response time
• Timestamp

Retry Behavior

Failed deliveries are retried automatically with exponential backoff. After the configured number of retries, the delivery is marked as failed but the webhook remains active for future events.

Security Best Practices

• Use HTTPS: Always use HTTPS endpoints for webhooks
• Use Secrets: Store API keys and tokens in Webhook Secrets rather than hardcoding in templates
• Enable Signing: Configure a signing secret and verify signatures in your receiving application
• Restrict Access: If possible, whitelist DFIRe's IP address in your receiving application
• Monitor Failures: Review delivery history for failures that might indicate configuration issues