# File download

Endpoint: POST file-download
Version: v1
Security: X-Signature

## Header parameters:

  - `X-Signature` (string, required)
    Example: "X-Signature: t=1492774577,v1=5257a869..."

## Request fields (application/json):

  - `version` (string)
    The version of the event.
    Example: "1"

  - `id` (string)
    The unique identifier for the event. This can be used as an idempotency key.
    Example: "c478966c-f927-411c-b919-179832d3d50c"

  - `timestamp` (integer)
    When the event occurred, formatted as a UNIX timestamp (in seconds).
    Example: 1698604061

  - `category` (string)
    The category of the event.
    Enum: "ACTIVITY"

  - `description` (string)
    The description of the event. Note: this is subject to change and should not be used to match on this object.
    Example: "employee@example.com downloaded file.exe from https://phishing-site.com/downloads"

  - `object` (string)
    The object that was created.
    Enum: "FILE_DOWNLOAD"

  - `friendlyName` (string)
    The friendly name of this object. Note: this is subject to change and should not be used to match on this object.
    Example: "File download"

  - `new` (object)
    This object represents a file download event, indicating an employee has downloaded a file.

  - `new.employee` (object)
    This object represents an employee in your organization.

  - `new.employee.id` (string)
    Unique identifier for the employee
    Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

  - `new.employee.email` (string)
    Primary email address of the employee
    Example: "john.hill@example.com"

  - `new.employee.firstName` (string)
    First name of the employee
    Example: "John"

  - `new.employee.lastName` (string)
    Last name of the employee
    Example: "Hill"

  - `new.employee.department` (string)
    Department - as provided by connected API integrations
    Example: "Security Engineering"

  - `new.employee.location` (string)
    Location - as provided by connected API integrations
    Example: "New York"

  - `new.employee.licensed` (boolean)
    Whether the employee is licensed on the Push platform
    Example: true

  - `new.employee.creationTimestamp` (integer)
    When this employee was created, formatted as a UNIX timestamp (in seconds)
    Example: 1698669223

  - `new.employee.chatopsEnabled` (boolean)
    Whether the employee has ChatOps enabledDeprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version.
    Example: true

  - `new.browserId` (string)
    Unique identifier of the browser instance.
    Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

  - `new.filename` (string)
    Name of the downloaded file.
    Example: "file.exe"

  - `new.startUrl` (string,null)
    Original download URL. Null if not provided.
    Example: "https://phishing-site.com/downloads/file.exe"

  - `new.url` (string,null)
    Final URL after redirects. Null if not provided.
    Example: "https://phishing-site.com/downloads/file.exe"

  - `new.referrerUrl` (string,null)
    Referrer URL of the download request. Null if not provided.
    Example: "https://phishing-site.com/downloads"

  - `new.tabUrl` (string,null)
    URL of the tab that initiated the download. Null if not provided.
    Example: "https://phishing-site.com/downloads"

  - `new.safe` (boolean)
    Whether the browser considers the download safe. Always true on Firefox (danger property unsupported).
    Example: true

  - `new.unsafeReason` (string,null)
    Browser-assessed download danger reason, based on Chrome's DangerType values. Null if the download is considered safe. See https://developer.chrome.com/docs/extensions/reference/api/downloads#type-DangerType.
    Enum: "file", "url", "content", "uncommon", "host", "unwanted", "dangerous", "potentiallyUnwanted", "allowlistedByPolicy", "asyncScanning", "asyncLocalPasswordScanning", "passwordProtected", "blockedTooLarge", "sensitiveContentWarning", "sensitiveContentBlock", "deepScannedFailed", "deepScannedSafe", "deepScannedOpenedDangerous", "promptForScanning", "promptForLocalPasswordScanning", "accountCompromise"

  - `new.mimeType` (string,null)
    MIME type of the downloaded file.
    Example: "application/octet-stream"

  - `new.fileSizeBytes` (integer,null)
    Total file size in bytes.
    Example: 1024

  - `new.state` (string)
    Terminal state of the download.
    Enum: "COMPLETE", "INTERRUPTED"

  - `new.interruptReason` (string,null)
    Reason the download was interrupted. Null when state is complete.
    Enum: "FILE_FAILED", "FILE_ACCESS_DENIED", "FILE_NO_SPACE", "FILE_NAME_TOO_LONG", "FILE_TOO_LARGE", "FILE_VIRUS_INFECTED", "FILE_TRANSIENT_ERROR", "FILE_BLOCKED", "FILE_SECURITY_CHECK_FAILED", "FILE_TOO_SHORT", "FILE_HASH_MISMATCH", "FILE_SAME_AS_SOURCE", "NETWORK_FAILED", "NETWORK_TIMEOUT", "NETWORK_DISCONNECTED", "NETWORK_SERVER_DOWN", "NETWORK_INVALID_REQUEST", "SERVER_FAILED", "SERVER_NO_RANGE", "SERVER_BAD_CONTENT", "SERVER_UNAUTHORIZED", "SERVER_CERT_PROBLEM", "SERVER_FORBIDDEN", "SERVER_UNREACHABLE", "SERVER_CONTENT_LENGTH_MISMATCH", "SERVER_CROSS_ORIGIN_REDIRECT", "USER_CANCELED", "USER_SHUTDOWN", "CRASH"

  - `new.byExtensionId` (string,null)
    ID of the browser extension that initiated the download. Null if not extension-initiated.
    Example: "example-extension-id"

  - `new.byExtensionName` (string,null)
    Name of the browser extension that initiated the download. Null if not extension-initiated.
    Example: "Example Extension"

  - `new.incognito` (boolean)
    Whether the download occurred in an incognito/private window.
    Example: true

  - `new.startTimestamp` (integer)
    Unix timestamp (seconds) when the download started.
    Example: 1698604061

  - `new.endTimestamp` (integer)
    Unix timestamp (seconds) when the download completed or was interrupted.
    Example: 1698604061

  - `new.downloadSource` (string)
    Source of the download.
    Enum: "NETWORK", "BLOB_URL", "DATA_URL"


## Response 2XX fields