Webhooks

Webhooks allow you to receive real-time HTTP notifications from Detectify when events occur. This enables custom integrations with any system that can receive HTTP POST requests.

How Webhooks Work

When a configured event occurs in Detectify (such as a new vulnerability finding), Detectify sends an HTTP POST request to your specified webhook URL with a JSON payload containing the event details. Your receiving system can then process the data and take any action needed.

Setup

Prerequisites

• A Detectify account with admin or team admin permissions
• An HTTP endpoint that can receive POST requests from the internet

Configuration Steps

1. In Detectify, navigate to Settings > Integrations.
2. Find Webhooks and click Configure.
3. Click Add Webhook.
4. Enter the following details:
   • URL: The HTTPS endpoint where Detectify should send events
   • Events: Select which event types trigger the webhook (new findings, scan completions, asset changes)
   • Severity filter: Optionally limit finding notifications to specific severity levels
5. Click Save.

Testing the Webhook

Click Send Test Event to send a sample payload to your endpoint. Verify that:

• Your endpoint receives the request
• The payload is parsed correctly
• Your system processes the event as expected

Payload Format

Webhook payloads are sent as JSON in the HTTP request body. A typical finding event looks like:

{
  "event_type": "finding",
  "timestamp": "2025-01-15T14:30:00Z",
  "finding": {
    "title": "SQL Injection",
    "severity": "critical",
    "asset": "app.example.com",
    "url": "https://app.example.com/api/users?id=1",
    "parameter": "id",
    "description": "SQL injection detected in the id parameter",
    "remediation": "Use parameterized queries..."
  }
}

The exact payload structure varies by event type. Detectify includes all relevant finding details so your receiving system has the context needed to take action.

Use Cases

Webhooks are commonly used for:

• Custom ticketing workflows — Create tickets in systems without native integration
• ChatOps — Post findings to communication platforms via their incoming webhook APIs
• Automated remediation — Trigger automated fixes or configuration changes when specific vulnerability types are detected
• Data aggregation — Feed vulnerability data into custom dashboards or reporting tools
• Compliance logging — Forward finding data to audit log systems

Retry Behavior

If your endpoint returns an HTTP error status (4xx or 5xx) or is unreachable, Detectify retries the delivery with exponential backoff. After multiple failed attempts, the webhook is marked as unhealthy. You can view delivery status and retry failed events in the webhook configuration page.

Security Considerations

• Use HTTPS endpoints only to protect webhook payloads in transit
• Validate the source by checking request headers or implementing a shared secret
• Handle payloads idempotently since retries may deliver the same event more than once
• Respond quickly with a 2xx status code to acknowledge receipt; process the event asynchronously if needed

Disconnecting

To remove a webhook, navigate to Settings > Integrations > Webhooks, select the webhook, and click Delete. Pending events for the deleted webhook are discarded.