Send results to a webhook

Deliver rendered findings and agent outputs as authenticated JSON POST requests to an endpoint you control.

The webhook integration sends the complete rendered action payload as an HTTP POST request. Any 2xx response marks the submission successful.

Define the receiver contract

Your endpoint must:

accept POST requests with a JSON body
respond within 10 seconds
return a 2xx status after it accepts the payload
handle retries or deduplicate requests when external side effects matter

Webhook response bodies are ignored. Dreadnode does not extract an external ID or URL from the response.

Create the connection

Open Org Settings → Integrations.
In Connections, choose the + button (Add connection).
Set Destination to Webhook.
Enter a descriptive Name and the destination URL.
Add Headers JSON when the receiver requires custom headers.
Add a Bearer token when the receiver uses bearer authentication.
Choose Create, then choose Test connection on the saved connection.

Header names and values must be strings:

{
  "X-Source": "dreadnode",
  "X-Environment": "production"
}

For API clients, use these canonical fields:

{
  "name": "SOC intake webhook",
  "type": "webhook",
  "config": {
    "url": "https://security.example.net/hooks/dreadnode",
    "headers": {
      "X-Source": "dreadnode"
    }
  },
  "credentials": {
    "bearer_token": "REPLACE_WITH_WEBHOOK_TOKEN"
  }
}

The URL, custom header values, and bearer token are encrypted and write-only after creation. Choose Edit connection to change the URL, headers, or token. Leave a sensitive field blank to keep its current value.

Create the payload

Webhooks accept any rendered JSON object. This example sends a stable event name and selected output fields:

{
  "event": "dreadnode.item.submitted",
  "item_id": "{{item.id}}",
  "item_type": "{{item.item_type}}",
  "project": "{{project.key}}",
  "title": "{{title}}",
  "severity": "{{data.severity}}",
  "data": "{{data}}"
}

Because {{data}} fills the whole value, it remains a JSON object. Embedded tokens become strings. Add this payload as Template JSON when you create the webhook’s submission action.

Authenticate requests

When you configure a bearer token, Dreadnode sends:

Authorization: Bearer REPLACE_WITH_WEBHOOK_TOKEN
Content-Type: application/json
X-Source: dreadnode

The bearer token controls the Authorization header. Use Headers JSON for other authentication schemes instead of setting both mechanisms.

Meet webhook network rules

SaaS webhook URLs must use HTTPS. Dreadnode rejects localhost, loopback, link-local, private, and cloud metadata targets under the default configuration.

Enterprise and self-hosted operators can allow HTTP and private targets with:

INTEGRATIONS_ALLOW_PRIVATE_WEBHOOK_TARGETS=true

Localhost, loopback, link-local, and cloud metadata addresses remain blocked. The API workers must resolve and reach the target host from the deployment network.

Handle failures and retries

Result	Dreadnode behavior
`2xx` response	Marks the attempt successful.
Non-`2xx` response	Marks the attempt failed.
Connection failure	Records `Unable to reach webhook URL`.
Response after 10 seconds	Records `Webhook submission timed out`.