Back to binalyze.com

Event Subscription

This feature will be added to AIR version 4.33 - publicly available 11th Feb 2025

This feature will be added to AIR version 4.33 - publicly available 11th Feb 2025

Overview

The Event Subscription feature enables users to register a URL that the system will call with event details. This allows users to integrate with external systems by sending JSON payloads to the specified URL whenever subscribed events occur.

Key Features

  1. URL Registration: Users can provide a URL that will be called with a POST request containing event information in a JSON payload.

  2. Secure Headers: Every request to the registered URL includes an Authorization: Bearer <token> header for authentication.

  3. Event Selection: Users can select one or multiple events they want the system to notify their URL about.

  4. Subscription Status: Users can activate or deactivate subscriptions at any time.

  5. Audit Logs: The system logs errors or issues when the registered URL cannot be accessed, providing insights into potential failures.

Example HTTP request

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json } "eventName": "TaskProcessingCompletedEvent", "organizationId": 1, "data" : { "taskId": "12345", "taskDetailsUrl": "/#/task-details/12345", "taskType": "Export", "assetId": "67890" } }

Audit Logs

The system maintains logs for monitoring calls:

  • Failed attempts to access the URL (e.g., 404 Not Found, 500 Internal Server Error) are recorded.

  • Logs are accessible in the "Audit Logs" section, providing timestamps and error details for troubleshooting.

Event List

DeploymentTokenRegeneratedEvent

This event is triggered when a deployment token is regenerated for an organization. The old token will be invalidated, and a new token will be used for deployments.

Parameters

  • organizationId: (string) The ID of the organization.

  • organizationName: (string) The name of the organization.

  • oldToken: (string) The old deployment token.

  • newToken: (string) The new deployment token.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "DeploymentTokenRegeneratedEvent", "organizationId": 1, "data": { "organizationId": "1", "organizationName": "example", "oldToken": "oldToken", "newToken": "newToken" } }

CaseFileSavedEvent

This event is triggered when a case file is saved to the AIR by Off-Network or Assets.

Parameters

  • assetId: (string) The ID of the asset

  • taskId: (string) The ID of the task.

  • reportURL: (string) Report URL.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "CaseFileSavedEvent", "organizationId": 1, "data": { "assetId": "assetId", "taskId": "taskId", "reportURL": "reportUrl" } }

TaskProcessingCompletedEvent

This event is triggered when a Task’s processes are completed. These processes may include actions such as data collection, analysis, reporting, or other workflow steps associated with the task. Completion indicates that all required steps have been successfully executed.

Parameters

  • taskId: (string) The ID of the task.

  • taskDetailsUrl: (string) The URL of the task details

  • taskType: (string) The task type of the task (Acquire evidence, Triage vs.)

  • assetId: (string) The assetId which is assigned to the task.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TaskProcessingCompletedEvent", "organizationId": 1, "data": { "taskId": "taskId", "taskDetailsUrl": "url", "taskType": "taskType", "assetId": "assetId", } }

TaskProcessingFailedEvent

This event is triggered when a Task’s processes fail. This could occur due to various reasons such as resource unavailability, misconfiguration, or unexpected errors during execution. Users should review the task details and the associated error reason to identify the root cause and take corrective actions, such as retrying the task or fixing the underlying issues.

Parameters

  • taskId: (string) The ID of the task.

  • taskDetailsUrl: (string) The URL of the task details

  • taskType: (string) The task type (Acquire evidence, Triage vs.)

  • assetId: (string) The assetId which is assigned to the task.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TaskProcessingFailedEvent", "organizationId": 1, "data": { "taskId": "taskId", "taskDetailsUrl": "url", "taskType": "taskType", "assetId": "assetId", } }

AirVersionAvailableEvent

This event is triggered when a new version of the AIR product is available. It informs the system or users about the newly available version and compares it with the current version in use.

Parameters

  • newVersion: (string) The new version of the AIR that is now available.

  • currentVersion: (string) The current version of the AIR in use.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "AirVersionAvailableEvent", "organizationId": 1, "data": { "newVersion": "2.0.0", "currentVersion": "1.0.0" } }

AssetCreatedEvent

This event is triggered when a new asset is created in the system. It provides details about the asset, including its ID, name, type, and creation timestamp.

Parameters

  • id: (string) The unique identifier of the asset.

  • name: (string) The name of the asset.

  • type: (string) The type of the asset

  • createdAt: (string) The date when the asset was created.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "AssetCreatedEvent", "organizationId": 1, "data": { "id": "asset-id", "name": "Asset Name", "type": "Asset Type", "createdAt": "2025-01-28T12:00:00Z" } }

CaseArchivedEvent

This event is triggered when a case is archived in the system. It provides details about the archived case, including its ID and name.

Parameters

  • id: (string) The unique identifier of the archived case.

  • name: (string) The name of the archived case.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "CaseArchivedEvent", "organizationId": 1, "data": { "id": "case-id", "name": "Case Name" } }

CaseClosedEvent

This event is triggered when a case is closed in the system. It provides details about the closed case, including its ID, name, and the timestamp when it was closed.

Parameters

  • id: (string) The unique identifier of the closed case.

  • name: (string) The name of the closed case.

  • closedOn: (string) The date when the case was closed.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "CaseClosedEvent", "organizationId": 1, "data": { "id": "case-id", "name": "Case Name", "closedOn": "2025-01-28T12:00:00Z" } }

CaseCreatedEvent

This event is triggered when a new case is created in the system. It provides details about the created case, including its ID, name, and the owner user of the case.

Parameters

  • id: (string) The unique identifier of the created case.

  • name: (string) The name of the created case.

  • ownerUser: (string) The user who owns the created case.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "CaseCreatedEvent", "organizationId": 1, "data": { "id": "case-id", "name": "Case Name", "ownerUser": "user-name" } }

EndpointDeletedEvent

This event is triggered when an endpoint is deleted from the system. It provides details about the deleted endpoint, including its ID, name, label, version, and platform.

Parameters

  • id: (string) The unique identifier of the deleted endpoint.

  • name: (string) The name of the deleted endpoint.

  • label: (string) The label associated with the deleted endpoint.

  • version: (string) The version of the deleted endpoint.

  • platform: (string) The platform of the deleted endpoint.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "EndpointDeletedEvent", "organizationId": 1, "data": { "id": "endpoint-id", "name": "Endpoint Name", "label": "Endpoint Label", "version": "1.0.0", "platform": "Platform Name" } }

EndpointIsolationStatusUpdatedEvent

This event is triggered when the isolation status of an endpoint is updated. It provides details about the endpoint and the changes in its isolation status.

Parameters

  • endpointId: (string) The unique identifier of the endpoint whose isolation status has been updated.

  • oldStatus: (string) The previous isolation status of the endpoint.

  • newStatus: (string) The new isolation status of the endpoint.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "EndpointIsolationStatusUpdatedEvent", "organizationId": 1, "data": { "endpointId": "endpoint-id", "oldStatus": "isolation-enabled", "newStatus": "isolation-disabled" } }

EndpointRegisteredEvent

This event is triggered when a new endpoint is registered in the system. It provides details about the registered endpoint, including its ID, organization ID, name, platform, and version.

Parameters

  • id: (string) The unique identifier of the registered endpoint.

  • organizationId: (string) The ID of the organization that the endpoint belongs to.

  • name: (string) The name of the registered endpoint.

  • platform: (string) The platform associated with the registered endpoint.

  • version: (string) The version of the registered endpoint.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "EndpointRegisteredEvent", "organizationId": 1, "data": { "id": "endpoint-id", "organizationId": "org-id", "name": "Endpoint Name", "platform": "Platform Name", "version": "1.0.0" } }

EndpointUninstalledEvent

This event is triggered when an endpoint is uninstalled from the system. It provides details about the uninstalled endpoint, including its ID, name, platform, version, and the source of the uninstallation.

Parameters

  • id: (string) The unique identifier of the uninstalled endpoint.

  • name: (string) The name of the uninstalled endpoint.

  • platform: (string) The platform associated with the uninstalled endpoint.

  • version: (string) The version of the uninstalled endpoint.

  • uninstallSource: (string) The source of the uninstallation, such as whether it was uninstalled via task, user, or due to migration

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "EndpointUninstalledEvent", "organizationId": 1, "data": { "id": "endpoint-id", "name": "Endpoint Name", "platform": "Platform Name", "version": "1.0.0", "uninstallSource": "user" } }

TasksHaveBeenTakenByEndpointEvent

This event is triggered when an endpoint has taken a set of tasks. It provides details about the endpoint and the tasks that have been assigned to it.

Parameters

  • endpointId: (string) The unique identifier of the endpoint that has taken the tasks.

  • taskCount: (number) The number of tasks that have been assigned to the endpoint.

  • taskNames: (array of strings) The names of the tasks that have been assigned to the endpoint.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TasksHaveBeenTakenByEndpointEvent", "organizationId": 1, "data": { "endpointId": "endpoint-id", "taskCount": 3, "taskNames": ["Task 1", "Task 2", "Task 3"] } }

DroneFileSavedEvent

This event is triggered when a file related to a drone task is saved in the system. It provides details about the saved file, including the file path, the associated task ID, and the endpoint ID.

Parameters

  • droneZipPath: (string) The path to the saved drone file (ZIP file).

  • taskId: (string) The ID of the task associated with the saved drone file.

  • endpointId: (string) The ID of the endpoint associated with the saved drone file.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "DroneFileSavedEvent", "organizationId": 1, "data": { "droneZipPath": "/path/to/drone/file.zip", "taskId": "task-id", "endpointId": "endpoint-id" } }

OrganizationCreatedEvent

This event is triggered when a new organization is created in the system. It provides details about the newly created organization, including its ID and name.

Parameters

  • id: (string) The unique identifier of the created organization.

  • name: (string) The name of the created organization.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "OrganizationCreatedEvent", "organizationId": 1, "data": { "id": "organization-id", "name": "Organization Name" } }

OrganizationDeletedEvent

This event is triggered when an organization is deleted from the system. It provides details about the deleted organization, including its ID and name.

Parameters

  • id: (string) The unique identifier of the deleted organization.

  • name: (string) The name of the deleted organization.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "OrganizationDeletedEvent", "organizationId": 1, "data": { "id": "organization-id", "name": "Organization Name" } }

OrganizationUpdatedEvent

This event is triggered when an organization is updated in the system. It provides details about the updated organization, including its name and the fields that were updated.

Parameters

  • name: (string) The name of the updated organization.

  • updatedFields: (string) A comma-separated list of the fields that were updated in the organization.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "OrganizationUpdatedEvent", "organizationId": 1, "data": { "name": "Updated Organization Name", "updatedFields": "field1, field2, field3" } }

RelayServerRegisteredEvent

This event is triggered when a new relay server is registered in the system. It provides details about the registered relay server, including its ID, name, endpoint ID, version, and endpoint name.

Parameters

  • id: (string) The unique identifier of the registered relay server.

  • name: (string) The name of the registered relay server.

  • endpointId: (string) The ID of the endpoint associated with the relay server.

  • version: (string) The version of the relay server.

  • endpointName: (string) The name of the endpoint associated with the relay server.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "RelayServerRegisteredEvent", "organizationId": 1, "data": { "id": "relay-server-id", "name": "Relay Server Name", "endpointId": "endpoint-id", "version": "1.0.0", "endpointName": "Endpoint Name" } }

RelayServerRemovedEvent

This event is triggered when a relay server is removed from the system. It provides details about the removed relay server, including its ID, name, and the associated endpoint ID.

Parameters

  • id: (string) The unique identifier of the removed relay server.

  • name: (string) The name of the removed relay server.

  • endpointId: (string) The ID of the endpoint associated with the removed relay server.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "RelayServerRemovedEvent", "organizationId": 1, "data": { "id": "relay-server-id", "name": "Relay Server Name", "endpointId": "endpoint-id" } }

TaskAssignedToEndpointEvent

This event is triggered when a task is assigned to an endpoint. It provides details about the task assignment, including the task name, endpoint name, case name, and the associated IDs.

Parameters

  • taskName: (string) The name of the assigned task.

  • endpointName: (string) The name of the endpoint the task is assigned to.

  • endpointId: (string) The unique identifier of the endpoint.

  • caseName: (string) The name of the case associated with the task.

  • assignmentId: (string) The unique identifier of the task assignment.

  • caseId: (string) The unique identifier of the case.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TaskAssignedToEndpointEvent", "organizationId": 1, "data": { "taskName": "Task Name", "endpointName": "Endpoint Name", "endpointId": "endpoint-id", "caseName": "Case Name", "assignmentId": "assignment-id", "caseId": "case-id" } }

TaskAssignmentCancelledEvent

This event is triggered when a task assignment to an endpoint is cancelled. It provides details about the cancelled task assignment, including the task's ID, name, type, and the endpoint it was assigned to.

Parameters

  • taskId: (string) The unique identifier of the cancelled task.

  • taskName: (string) The name of the cancelled task.

  • taskType: (string) The type of the cancelled task.

  • endpointName: (string) The name of the endpoint the task was assigned to.

  • endpointId: (string) The unique identifier of the endpoint.

  • taskAssignmentId: (string) The unique identifier of the cancelled task assignment.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TaskAssignmentCancelledEvent", "organizationId": 1, "data": { "taskId": "task-id", "taskName": "Task Name", "taskType": "Task Type", "endpointName": "Endpoint Name", "endpointId": "endpoint-id", "taskAssignmentId": "task-assignment-id" } }

TaskAssignmentDeletedEvent

This event is triggered when a task assignment is deleted. It provides details about the deleted task assignment, including the task’s name, type, and the endpoint to which it was assigned.

Parameters

  • taskName: (string) The name of the deleted task.

  • taskType: (string) The type of the deleted task.

  • endpointName: (string) The name of the endpoint the task was assigned to.

  • endpointId: (string) The unique identifier of the endpoint.

  • taskId: (string) The unique identifier of the deleted task.

  • taskAssignmentId: (string) The unique identifier of the deleted task assignment.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TaskAssignmentDeletedEvent", "organizationId": 1, "data": { "taskName": "Task Name", "taskType": "Task Type", "endpointName": "Endpoint Name", "endpointId": "endpoint-id", "taskId": "task-id", "taskAssignmentId": "task-assignment-id" } }

TaskCancelledEvent

This event is triggered when a task is cancelled. It provides details about the cancelled task, including its ID, name, and type.

Parameters

  • taskId: (string) The unique identifier of the cancelled task.

  • taskName: (string) The name of the cancelled task.

  • taskType: (string) The type of the cancelled task.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TaskCancelledEvent", "organizationId": 1, "data": { "taskId": "task-id", "taskName": "Task Name", "taskType": "Task Type" } }

TaskCompletedEvent

This event is triggered when a task is completed. It provides details about the completed task, including its ID, name, type, the organization it belongs to, and statistics about the assigned and completed endpoints.

Parameters

  • id: (string) The unique identifier of the completed task.

  • name: (string) The name of the completed task.

  • type: (string) The type of the completed task.

  • organizationId: (string) The ID of the organization to which the task belongs.

  • totalAssignedEndpoints: (number) The total number of endpoints assigned to the task.

  • totalCompletedEndpoints: (number) The total number of endpoints that have completed the task.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TaskCompletedEvent", "organizationId": 1, "data": { "id": "task-id", "name": "Task Name", "type": "Task Type", "organizationId": "org-id", "totalAssignedEndpoints": 5, "totalCompletedEndpoints": 4 } }

TaskDeletedEvent

This event is triggered when a task is deleted. It provides details about the deleted task, including its ID, name, and type.

Parameters

  • taskId: (string) The unique identifier of the deleted task.

  • taskName: (string) The name of the deleted task.

  • taskType: (string) The type of the deleted task.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TaskDeletedEvent", "organizationId": 1, "data": { "taskId": "task-id", "taskName": "Task Name", "taskType": "Task Type" } }

TaskScheduledForEndpointEvent

This event is triggered when a task is scheduled for an endpoint. It provides details about the task and the endpoint it is scheduled for, along with the associated case information.

Parameters

  • endpointName: (string) The name of the endpoint the task is scheduled for.

  • taskName: (string) The name of the scheduled task.

  • taskType: (string) The type of the scheduled task.

  • endpointId: (string) The unique identifier of the endpoint.

  • caseId: (string) The unique identifier of the associated case.

  • caseName: (string) The name of the associated case.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TaskScheduledForEndpointEvent", "organizationId": 1, "data": { "endpointName": "Endpoint Name", "taskName": "Task Name", "taskType": "Task Type", "endpointId": "endpoint-id", "caseId": "case-id", "caseName": "Case Name" } }

TriageRuleMatchedEvent

This event is triggered when a triage rule is matched for a task on an endpoint. It provides details about the matched rule, the associated task, and the endpoint involved.

Parameters

  • endpointId: (string) The unique identifier of the endpoint where the rule was matched.

  • endpointName: (string) The name of the endpoint where the rule was matched.

  • taskId: (string) The unique identifier of the associated task.

  • taskName: (string) The name of the associated task.

  • ruleName: (string) The name of the triage rule that was matched.

  • ruleType: (string) The type of the triage rule that was matched.

  • details: (object) Additional details or context about the matched rule.

HTTP request example

POST <your-path> HTTP/1.1 Host: <your-host> Authorization: Bearer <your-token> Content-Type: application/json { "eventName": "TriageRuleMatchedEvent", "organizationId": 1, "data": { "endpointId": "endpoint-id", "endpointName": "Endpoint Name", "taskId": "task-id", "taskName": "Task Name", "ruleName": "Rule Name", "ruleType": "Rule Type", "details": { "key": "value" } } }

PreviousCisco XDR IntegrationNextAIR API

Last updated

Was this helpful?