Skip to main content

Webhooks

Defused webhooks allow you to forward alert and intel events to any HTTP endpoint for automation, enrichment, or downstream processing (SIEM, SOAR, custom workflows).

Webhooks are evaluated in real time during alert processing and are designed to be simple, explicit, and predictable.

What Webhooks Can Trigger On​

Defused supports two types of webhook-triggering events:

Alert Events (Alert)​

These are alerts generated by your own deployed decoys and sensors (Defused EX).

  • Webhooks configured for alerts are tenant-scoped
  • Only alerts belonging to the same customer will ever trigger them
  • Typical use cases:
    • Ticket creation
    • Blocking automation
    • SOC notifications

Intel Events (Intel Feed)​

These are events sourced from the honeypot intelligence feed (Defused TF).

  • Intel webhooks are global subscriptions
  • Any intel event that matches your criteria will trigger
  • Intel events do not have a customer attached
  • Typical use cases:
    • Threat intelligence ingestion
    • External correlation
    • Research and enrichment pipelines

Webhook Configuration Fields​

This section explains the core webhook configuration options shown in the Webhook setup view.

These fields define where the webhook is sent, how it is sent, and how Defused authenticates to the receiving endpoint.

Webhook Name​

Required. A human-readable name for the webhook.

Used for:

  • Identifying the webhook in the UI
  • Execution logs and audit events
  • Dependency chains (when webhooks are run sequentially)

Example:

Blocklist workflow

Webhook URL​

Required. The full HTTP or HTTPS endpoint that Defused will send requests to when the webhook triggers.

Example:

https://example.com/webhooks/defused

HTTP Auth​

Optional. When enabled, Defused will include authentication credentials in the outgoing request.

Supported authentication methods:

  • Basic Auth (username and password)
  • Bearer Token
  • API Key

Authentication is applied using standard HTTP Authorization headers.

Headers​

Optional custom HTTP headers to include with the request.

Headers are sent in addition to authentication headers (if enabled).

Common use cases include:

  • API keys
  • Custom routing headers
  • Workflow identifiers

Example headers:

X-API-Key: 123456
X-Source: defused

HTTP Method​

Defines which HTTP method is used when sending the webhook.

Supported methods:

  • POST (recommended, default)
  • GET
  • PUT
  • PATCH
  • DELETE

For non-GET requests, the webhook payload is sent as JSON in the request body. For GET requests, payload fields are sent as query parameters.

Disable SSL Verification​

Optional. When enabled, Defused will not validate the TLS certificate of the destination endpoint.

This is useful for:

  • Internal testing
  • Self-signed certificates
  • Development environments

Warning: Disabling SSL verification is not recommended for production endpoints unless you fully trust the destination.

How Matching Works​

Webhooks are triggered only if their match rules are satisfied.

Matching is evaluated before any HTTP request is sent.

Match Structure​

Matches are defined as:

  • OR groups (any)
  • containing AND rules (all)

Example:

{
  "any": [
    {
      "all": [
        { "field": "alert_severity", "op": "eq", "value": "major" },
        { "field": "alert_sensor_type", "op": "eq", "value": "Ivanti Connect Secure" }
      ]
    }
  ]
}

Payload Fields and Testing​

The Payload fields section allows you to control what data is sent to the destination endpoint and how it is structured.

You can either:

  • Select individual fields to auto-generate a JSON template, or
  • Start from a minimal or verbose template and customize it manually

Selected fields are converted into a JSON payload using Defused placeholders.

Payload Field Selection​

Each checkbox represents a field that can be included in the webhook payload.

When selected, Defused automatically inserts the corresponding placeholder into the JSON template.

Common fields include:

  • Alert Type
  • Attacker IP
  • Decoy IP
  • Decoy Name
  • Datetime
  • Location
  • Raw Data

You can freely modify the JSON structure, rename keys, or nest fields, as long as Defused placeholders remain unchanged.

JSON Payload Editor​

The JSON editor shows the payload that will be sent when the webhook fires.

Placeholders use the format:

<<field>>

These placeholders are replaced at runtime with event data.

Important rules:

  • Placeholders must remain unchanged (including brackets)
  • The payload must be valid JSON after substitution
  • Raw Data is automatically escaped to remain JSON-safe

HTTP Representation​

The HTTP representation preview shows the exact HTTP request Defused will send when the webhook triggers.

This includes:

  • HTTP method
  • Headers
  • Request body
  • Authentication headers (if configured)

You can copy this request as a cURL command and replay it manually.

Testing Your Webhook​

Before relying on a webhook in production, you should verify that your endpoint receives and parses the payload correctly.

A simple and recommended way to test is to use a temporary webhook inspection service such as:

https://webhook.site

Steps:

  1. Create a temporary URL on webhook.site
  2. Paste the URL into the Webhook URL field
  3. Trigger a matching alert or intel event
  4. Inspect the received request and payload

This allows you to confirm:

  • The webhook fires as expected
  • Headers are set correctly
  • Authentication is applied
  • Payload fields arrive in the correct format

Testing with a webhook inspection service helps avoid integration issues when connecting Defused to production systems.

After Saving​

Once saved:

  • The webhook becomes active immediately
  • It is evaluated against incoming events in real time
  • Execution happens asynchronously and does not block alert processing

If a webhook does not meet its match conditions, it is silently skipped.