File scanned notifications

Overview

File Scanned webhook notifications allow you to receive real-time alerts whenever a file has been scanned by MetaDefender Storage Security. This feature is useful if you need to:

  • Track the outcome of file scans for auditing or compliance.
  • Integrate scan results into external systems (e.g., ticketing, alerting, SIEM).
  • Trigger automated workflows based on file status (e.g., quarantine, user notification).

Setup

  1. Go to Settings > Notifications in the MetaDefender Storage Security console.
  2. Select Send a webhook notification when a file is scanned under the Webhook Notifications section
  3. Choose whether you want to receive notifications for all scanned files or only blocked files.
  4. Enter the Destination Address (your endpoint).
  5. Select the Request Type (POST or PUT).
  6. (Optional) Add any custom HTTP headers.
  7. Save the configuration.

Configuration Details

  • Destination address – The URL of the receiving system (must accept HTTP requests).
  • Request type – Either POST or PUT.
  • Headers – Optional key-value pairs (e.g., Authorization: Bearer <token>).
  • Notification scope – Choose between:
    • All scanned files → You will receive a notification for every file scanned.
    • Blocked only → You will only receive notifications when a file is marked as blocked in MetaDefender Storage Security (see File Definition)

Webhook Payload

When triggered, the webhook sends a JSON request body to your configured endpoint.

Webhook payload
Copy

Field Reference

FieldTypeExample ValueDescription
FileIdstring (UUID)0198f02f-ed4d-7c0d-8668-1036d322209cUnique identifier of the file.
FileNamestringfile.txtOriginal file name.
FilePathstringfolder/file.txtFile's relative path.
FileStatusstringAllowed /BlockedFile status based on MDSS file definitions
CoreScanResultstringNo Threat DetectedResult from Scan instance.
FileStatestring

Failed / Canceled /

FailedRemediation / Available

File status in MDSS.
RemediationResultarray[string]["AllowedKept: Applied"]Array of remediations applied and their result
ScanCompletedTimeStampdatetime (UTC)2025-08-28T10:20:24.974998ZTime when scan completed.
WorkflowNamestringDefault WorkflowName of the workflow used.
Rulesarray[string]["MetaDefender Storage Security"]Workflow rules applied.
ExceptionDetailsstring""Details of any exceptions during scan.
RemediationErrorsarray[string][]Errors during remediation, if any.
WebhookNotificationTypestringFileScannedIdentifies the notification type.

Delivery Behavior

  • Webhooks are delivered as standard HTTP requests.
  • Delivery is best-effort → if the destination is invalid, the request is logged in the Audit page, but no retries are performed.
  • Payload size is typically small (JSON only, no file contents).

Security Considerations

  • Configure HTTPS endpoints to ensure data is transmitted securely.
  • Use authentication headers (e.g., API tokens) to protect your webhook endpoint.
  • Ensure your endpoint validates payloads before processing.

Troubleshooting

  • No webhook received → Verify the endpoint URL and request type (POST/PUT).
  • Audit shows delivery failed → Endpoint is invalid. Fix and test again.
  • Authentication errors → Confirm your endpoint accepts the headers you configured.
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
Next to read:
External Loggers Configuration
On This Page
File scanned notificationsOverviewSetupConfiguration DetailsWebhook PayloadField ReferenceDelivery BehaviorSecurity ConsiderationsTroubleshooting