Finding webhooks

Detectant can send an HTTPS webhook when a direct API scan or enabled S3 integration finds a suspicious or malicious file. Configure the destination and select Webhook under Dashboard → Settings → Notification settings. You can use webhook delivery by itself or together with email.

Event

Every notification uses the finding.detected event type. The request body is JSON and the detected_at value is an ISO 8601 timestamp.

For a direct API scan:

1
{
2
  "type": "finding.detected",
3
  "source": {
4
    "type": "api"
5
  },
6
  "finding": {
7
    "scan_id": "scan_01JEXAMPLE",
8
    "verdict": "malicious",
9
    "detection": "Malicious content",
10
    "reason": "The file matched one or more malicious indicators.",
11
    "size_bytes": 24812,
12
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13
    "detected_at": "2026-08-30T10:00:00.000Z"
14
  },
15
  "file": {
16
    "filename": "invoice.pdf"
17
  }
18
}

For an S3 integration, source identifies the integration and file identifies the exact object:

1
{
2
  "type": "finding.detected",
3
  "source": {
4
    "type": "s3",
5
    "integration_id": "162f1d7b-0f97-48af-b7ea-1fbc7a7c19e4",
6
    "integration_name": "Customer uploads"
7
  },
8
  "finding": {
9
    "scan_id": "scan_01JEXAMPLE",
10
    "verdict": "suspicious",
11
    "detection": "File type mismatch",
12
    "reason": "The file content does not match its declared type.",
13
    "size_bytes": 24812,
14
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15
    "detected_at": "2026-08-30T10:00:00.000Z"
16
  },
17
  "file": {
18
    "bucket": "customer-uploads",
19
    "object_key": "incoming/invoice.pdf"
20
  }
21
}

verdict is either suspicious or malicious. Treat fields you do not recognize as forwards-compatible additions.

Verify the signature

Detectant signs the exact raw request body using the signing secret shown in notification settings. The request includes these Standard Webhooks headers:

• webhook-id: a stable identifier for this finding notification. Use it to deduplicate processing.
• webhook-timestamp: the signing time as Unix seconds.
• webhook-signature: one or more versioned signatures, currently v1,<base64-signature>.

To calculate the expected signature:

1. Remove the whsec_ prefix from the signing secret and Base64-decode the remainder.
2. Join the webhook ID, timestamp and unmodified raw body with periods: <id>.<timestamp>.<raw-body>.
3. Calculate HMAC-SHA256 with the decoded secret and Base64-encode the result.
4. Compare it with the v1 signature using a timing-safe comparison.

Reject requests with missing headers, an invalid signature, or a timestamp outside a short tolerance such as five minutes. Verify the signature before parsing JSON, and never log the signing secret or full request headers.

Delivery behavior

The endpoint must use HTTPS and a public hostname. Detectant waits up to five seconds and accepts any 2xx response as successful. Redirects and non-2xx responses are treated as failures. A failed delivery does not change the saved finding or scan result and is not currently retried automatically. Respond quickly after safely recording the event and perform slower work asynchronously.

Keep the signing secret private. If it is exposed, disable webhook delivery and contact Detectant support.