Event API

2026-11-03

EventAPI is FlightHub Sync's active notification service for pushing business events to third-party platforms in real time. When using EventAPI, note the following:

  • Users must verify the x-dji-signature field in the request header of their receiving service. The signature is calculated using HMAC-SHA256 based on the organization token to verify the authenticity of the request source.
  • Users can configure notification rules, select the event types to subscribe to, and subscribe to data from all projects or specific projects.
  • The receiving endpoint supports both HTTP and HTTPS protocols.
  • FlightHub 2 pushes these event notifications using fixed IP addresses. Servers in different regions use different IP addresses. For the on-premises version of FlightHub, the specific IP addresses depend on your server.
Country/RegionIP
EU Server + Global Server18.198.174.64
3.64.50.113
3.71.214.14
63.177.169.61
52.3.45.199
52.55.215.248
52.73.49.179
34.237.190.206
34.237.182.49
34.228.131.169


Feature Entry

Access EventAPI under Organization Settings > FlightHub Sync > EventAPI Event Notifications.

On the EventAPI Event Notifications page, you can view and create Notification Rules, and view and download Delivery Logs.



Notification Rule Configuration

The notification rule list displays the following information:

  • Rule name: User-defined name, up to 60 characters.
  • Push address: Endpoint URL (supports HTTP and HTTPS).
  • Type: EventAPI or automated workflow.
  • Data scope: All projects or specific projects.
  • Subscribed events: List of selected event types.
  • Status: Enabled / Disabled.
  • Actions: Edit, Delete.

Note: If a rule covering All Projects already exists in the organization, creating a rule for specific projects displays a warning about duplicate event notifications.



Create an EventAPI Notification Rule

Click Create in the upper-right corner of the Notification Rule Configuration list and select EventAPI.

  • Rule name: Required. Supports a custom rule name.
  • Receiving address: Required. Supports HTTP and HTTPS protocols.
  • Subscription data scope: Select All Projects or Specific Projects.
    • All Projects: Automatically includes all projects created in the future.
    • Specific Projects: Each project can be referenced by only one custom rule (excluding rules for all projects). Projects already referenced are grayed out.
  • Subscribed event types: Select one or more of the following notification events.
    • Sync File Sync Notification.
    • Obtain AI Alert List and Snapshot Content.
    • Model Post-Reconstruction Completion Notification.
    • Wayline File Creation Notification.
    • Exit Return-to-Home Notification.
    • FlightHub Mapping API - Model Reconstruction Progress.
    • Organization Annotation Added/Edited Notification.
    • RTSP Streaming Link Update Notification.
    • Custom Flight Area Data Sync Notification.
    • Automatic dispatch workflow events:
      • Automatic Dispatch Workflow Node Status Notification.
      • Automatic Dispatch Workflow Stage Event Notification.

Note: Automatic dispatch workflow events have two separate subscription options: Automatic Dispatch Workflow Node Status Notification (previously Automatic Dispatch Workflow Notification; only the name has changed) and Automatic Dispatch Workflow Stage Event Notification (new). You can subscribe to either or both independently. Subscriptions in existing rules are unaffected.


Sync File Sync Notification

{
  "id": "e3b0c442-73fc-1c14-9afb-f17e2fa6826a", // Unique event message ID (UUID)
  "type": "file_sync_success", // Event type: file sync success notification
  "created_at": 1767875288, // Event push timestamp (seconds)
  "data": {
    "task_id": "sync_task_10001", // Unique sync task ID
    "organization_id": "org_123456_xxxxxx", // Organization ID
    "project_id": "proj_789012_xxxxxx", // Project ID of the file
    "file_id": "file_345678_xxxxxx",  // File ID within FlightHub
    "file_type": "application/pdf", // File type (wayline: wayline; flight_record: flight record; model: model; media: media file)
    "file_external_key": "customer_storage/2026/01/report_09.pdf", // Object Key (storage path) of the file in the third-party storage bucket
    "file_bytes_size": 1048576, // File size (bytes)
    "fh2_file_path": "/project_docs/report/report_09.pdf", // Original logical path of the file in FlightHub 2
  }
}

Obtain AI Alert List and Snapshot Content

{
  "id": "e3b0c442-98fc-1c14-9afb-f17e2fa6826a", // Unique event message ID (UUID)
  "type": "ai_alert_record", // Event type: AI detection alert record
  "created_at": 1767875288, // Event push timestamp (seconds)
  "data": {
    "alert_uuid": "e3b0c442-98fc-1c14-9afb-f17e2fa6826a",// Unique alert record ID
    "algorithm_source": 100002, // // Algorithm source ID. Enumeration values:
                                    // 0: DJI official intelligent algorithm
                                    // 1: DJI official visible-light AI for people, vehicles, and boats
                                    // 2: DJI official infrared AI for people, vehicles, and boats
                                    // 3: DJI official infrared temperature detection AI
                                    // 255: AI-inside third-party onboard algorithm
                                    // 100001: AI-LINK third-party cloud algorithm
                                    // 100002: DJI multimodal object detection
    "drone_sn": "1581F6XXXXXX00A6XXXX", // Serial number of the aircraft performing the task
    "file_id": 123456, // Associated original media file ID
    "file_url": "https://file-storage.djicdn.com/example/path/image.jpg?auth_key=xxxx", // Original image download link (includes authentication parameters)
    "flight_id": "f17e2fa6-826a-48c5-a89a-fffe4093xxxx", // Associated flight ID
    "gateway_sn": "6QCDL8XXXXXX02XXXX", // Associated dock/gateway device serial number
    "interval_seconds": 0, // Alert interval or duration (seconds); defaults to 0 for non-cloud algorithms
    "labels": [
      "灯光"// Detected target label/type
    ],
    "location": {
      "altitude": 80.5, // Altitude when the alert occurred (meters)
      "latitude": 22.123456, // Latitude when the alert occurred. For onboard algorithms, this is the GPS coordinate at the center of the camera view at the time of the alert; for cloud algorithms, this is the aircraft position.
      "longitude": 113.123456, // Longitude when the alert occurred. For onboard algorithms, this is the GPS coordinate at the center of the camera view at the time of the alert; for cloud algorithms, this is the aircraft position.
    },
    "project_id": "fe2400a5-5a74-4cb5-8374-548b7eaxxxxx", // Project UUID
    "task_name": "FlyToTask_Inspect_ZoneA", // Associated flight task name
    "thumbnail_url": "https://oss-cn-hangzhou.aliyuncs.com/example/thumbnail.jpeg?Expires=1767961676&Signature=xxxx", // Thumbnail download link (includes signature and expiration time)
    "timestamp": 1767875275677, // Precise timestamp when AI detection occurred (milliseconds)
  }
}

Model Post-Reconstruction Completion Notification

{
  "type": "model_post_reconstruction",
  "org_id": "105ddd05-34ce-46b6-a872-cb32b8c98f64",
  "project_id": "38559b47-b972-4663-b1ce-5bd5a29224a4",
  "created_at": 1769414678,
  "data": {
    "id": "2e12cda7-c97d-4bf6-8f8f-btest9b18401", // Model ID
    "name": "xx模型",                      // Model name
    "object_key": "105ddd05-34ce-46b6-a872-cb32b8c98f64/38559b47-b972-4663-b1ce-5bd5a29224a4/etestbb3-2cf8-49af-b49b-64b1610032c7/模型", // Model object storage key
    "type": 8//8: 2D model, 9: 3D model
  }
}

Wayline File Creation Notification

{
  "type": "wayline_file_uploaded",
  "org_id": "1024dd05-34ce-46b6-a872-cb32b8c98f64",
  "project_id": "38535b47-b972-4663-b1ce-5bd5a29224a4",
  "created_at": 1769414678,
  "data": {
    "id": "testcda7-c97d-4bf6-8f8f-b490b9b18401", // Wayline ID
    "name": "新建航点航线(2)",           // Wayline name
    "object_key": "1testd05-34ce-46b6-a872-cb32b8c98f64/test9b47-b972-4663-b1ce-5bd5test24a4/e5testb3-2cf8-49af-b49b-64test0032c7/新建航点航线(2).kmz", // Wayline object storage key
    "type": 5 // File type; 5 indicates a wayline
  }
}

Exit Return-to-Home Notification

{
  "id": "9ab96be1-0231-4b2c-9892-2221188c323b",
  "type": "device_exit_return_home",
  "created_at": 1769400986,
  "data": {
    "action": 1,
    "event_type": "device_exit_return_home",
    "notify_type": "device_exit_return_home",
    "organization_uuid": "8test46f-2cd5-476b-9f33-415c98de11a5",
    "project_uuid": "8test9a5-d2ba-423d-a03e-e3b323c40810",
    "reason": null, // Reason for exiting RTH: "2":"Behavior tree initialization failed", "3":"Surrounded by obstacles", "4":"Flight restriction triggered", "5":"Obstacle too close", "6":"No GPS signal", "7":"GPS and VIO position output flags are false", "8":"GPS and VIO fused position error too large"
    "sn": "158TESTGD24BK0010114" // SN of the aircraft that unexpectedly exited RTH
  }
}

FlightHub Mapping API - Model Reconstruction Progress

{
    "msg_type": "model_reconstruction_percent_change", // Message type: model_reconstruction_percent_change=model reconstruction, model_zip_change=model compression
    "resource_uuid": "7417bac3-00a4-4e07-b078-233c77e3fdf9",
    "model_uuid": "3d33643c-de0d-4070-b155-8cf791e662e2",
    "model_status": 14, // Reconstruction status: 9=model compression, 12=waiting for resources, 13=failed to obtain resources, 14=reconstructing, 15=reconstruction successful, 16=reconstruction canceled
    "model_size": 37353992,
    "reconstruction_progress": 100, // Reconstruction progress, 0-100
    "error_code": 0, // Reconstruction error code
    "zip_status": 2, // Compression status: 1=compressing, 2=compression complete, 3=compression failed
    "zip_progress": 100, // Compression progress, 0-100
    "zip_file_key": "https://test-file-storage.djicdn.com/5a6f9d4b-2a38-4b4b-86f9-3a678da0bf4a/open_reconstruction/7417bac3-00a4-4e07-b078-233c77e3fdf9/3D/3d33643c-de0d-4070-b155-8cf791e662e2.zip?auth_key=1767942603-0-0-150d3c28868e91dd2446aef97c26de85", // Download URL of the compressed output file
}

Organization Annotation Added/Edited Notification

{
  "created_at": 1772803375,
  "data": {
    "count": 1,
    "download_url": "/openapi/v0.1/map/data-sync/files/33711783-bf96-440d-baa2-0e71afa1d485/f7356cd3-53de-4318-955f-306cbcc60ca2/0",
    "format": "kml-gz",
    "geometry_types": [
      "polygon"
    ],
    "sync_id": "annotation-f7356cd3-53de-4318-955f-306cbcc60ca2",
    "sync_type": 0
  },
  "id": "5df19eca-65cf-4975-a942-09fdcfd7bdf9",
  "org_id": "105ddd05-34ce-46b6-a872-cb32b8c98f64",
  "project_id": "33711783-bf96-440d-baa2-0e71afa1d485",
  "type": "map_geo_elements_update"
}

{
  "converter_name": "示例转换器",
  "converter_id": "29f4f54b-93af-4fd3-aed6-bd3d768082e9",
  "sn": "SN1234567890",
  "camera_index": "89-0-0",
  "device_callsign": "DRONE-01",
  "url": "rtsp://192.168.1.10:554/live/stream",
  "username": "rtsp_user",
  "password": "rtsp_password"
}

Automatic Dispatch Workflow Node Status Notification

Also known as Triggered Workflow Execution Progress Notification (previously Automatic Dispatch Workflow Notification; only the name has changed, and the notification payload is unchanged).

Pushes node execution progress for automatic dispatch workflows (incident-response workflows), enabling third-party systems to synchronize task status, identify terminal states, and track false-alarm flags in real time.

Note: To receive stage events throughout the incident-response lifecycle (dispatch, takeoff, flying to the scene, arrival, return to home, and completion), or one-click snapshots from the cockpit, subscribe to Triggered Workflow Stage Event Notification. These two event types are independent and can be subscribed to together.

{
  "event_type": "alert_workflow_progress",         // Event type: triggered workflow execution progress
  "event_id": "e3b0c442-73fc-1c14-9afb-f17e2fa6826a", // Unique event message ID (UUID)
  "org_id": "org_123456_xxxxxx",                   // Organization ID
  "project_id": "proj_789012_xxxxxx",              // Project ID (optional)
  "created_at": 1767875288,                        // Event push timestamp (seconds)
  "data": {
    "incident_id": "incident_2026062900001",       // Alert incident ID
    "workflow_uuid": "wf_uuid_xxxxxxxxxxxx",       // Workflow UUID
    "drone_sn": "1581F5BKD2380030XXXXX",           // Serial number of the aircraft performing the flight
    "node_type": "command_task",                   // Node type: command_task (FlyTo task) / device_actions (device actions)
    "status": 1,                                   // Current node status code, depending on node_type; enumeration values:
                                                   // node_type = "command_task" (FlyTo task node):
                                                   //   0: Pending             (non-terminal)
                                                   //   1: Executing           (non-terminal)
                                                   //   2: Successful          (terminal)
                                                   //   3: Manual intervention (terminal)
                                                   //   4: Execution failed    (terminal)
                                                   // node_type = "device_actions" (device action node):
                                                   //   0: Successful          (terminal)
                                                   //   1: Partially successful (terminal)
                                                   //   2: Failed              (terminal)
                                                   //   3: In progress         (non-terminal)
                                                   //   4: Manual intervention (terminal)
    "is_false_alarm": false,                       // Whether this is a false alarm (actual value returned only in terminal states; always false in non-terminal states)
    "flight_id": "task_uuid_xxxxxxxxxxxx"          // UUID of the current execution_task
  }
}

Automatic Dispatch Workflow Stage Event Notifications

Also known as Triggered Workflow Stage Event Notification. Pushes stage events throughout the incident-response lifecycle and supports one-click snapshot notifications from the cockpit, allowing third-party systems such as CAD, VMS, and middleware to synchronize incident-response progress in real time.

  • Coexists with Triggered Workflow Execution Progress Notification; neither affects the other.
  • The method of all events is fixed to dfr_lifecycle_event.
  • Use event_id for idempotent deduplication.

Event Types

event_typeDescriptionAffects Stage Status
stage_changeLifecycle stage changeYes
snapshotOne-click snapshot report from the cockpitNo

Common Fields

Every notification includes the following fields:

{
  "method": "dfr_lifecycle_event",              // Fixed value
  "version": "v1",                              // Protocol version
  "event_id": "evt_a1b2c3d4e5f6",               // Globally unique; used for idempotent deduplication
  "event_type": "stage_change",                 // stage_change | snapshot
  "org_id": "org_xxxx",                         // Organization ID
  "project_id": "proj_xxxx",                    // Project ID
  "incident_id": "MA-20260629001",              // Alert incident ID
  "workflow_uuid": "wf_uuid_xxxx",              // Workflow UUID
  "workflow_name": "南门警情",                   // Workflow name
  "task_id": "task_xxxx",                       // Task ID (null before takeoff)
  "drone_sn": "4BUCA1234567",                   // SN of the device performing the flight (null before device assignment)
  "occurred_at": 1767875288,                   // Timestamp when the event actually occurred
  "operator_user_id": "user_xxxx"               // Operator (internal FlightHub user_id; "system" when triggered automatically)
}

Lifecycle Stages

When event_type is stage_change, stage and stage_data are added to the common fields.

stageDescriptionTerminal State
dispatch_clickedDispatch clickedNo
dispatch_cancelledDispatch canceledYes
taking_offTaking offNo
flying_to_sceneFlying to the sceneNo
on_sceneArrived at the sceneNo
returningReturning to homeNo
mission_endedMission endedYes
media_uploadedMedia files uploadedNo
dispatch_clicked (Dispatch clicked):
{
  "stage": "dispatch_clicked",
  "stage_data": {
    "trigger_method": "manual",            // Trigger method: manual | auto
    "alert_level": 4,                      // Alert level at the time of triggering, 1-5
    "alert_title": "南门区域入侵告警",        // Alert title
    "target_location": {                   // Target location
      "longitude": 113.9526,
      "latitude": 22.5431,
      "target_altitude_agl": 83.0,         // Target point altitude (meters)
      "takeoff_altitude_alt": 120.0,       // Takeoff altitude (meters)
      "horizontal_distance_m": 20.0,       // Horizontal distance from the target point (meters)
      "return_altitude_alt": 88.0          // RTH altitude (meters)
    },
}

dispatch_cancelled (Dispatch canceled, terminal state):
{
  "stage": "dispatch_cancelled",
  "stage_data": {
    "cancel_reason": "user_cancelled",     // Cancellation reason: user_cancelled (canceled by user) | no_response (no response) | device_unavailable (device unavailable)
    "elapsed_since_dispatch_ms": 15000     // Time from dispatch_clicked to cancellation (milliseconds)
  }
}

taking_off (Taking off):
{
  "stage": "taking_off",
  "stage_data": {
    "drone_sn": "xxxxxxxx",                // SN of the device performing the flight
    "drone_model": "M5TD",                 // Device model
    "dock_sn": "xxxxxxxx",                 // Dock SN
    "assignment_method": "auto",           // Device assignment method: auto | manual
    "takeoff_altitude_alt": 120.0,         // Takeoff altitude (meters)
  }
}

flying_to_scene (Flying to the scene):
{
  "stage": "flying_to_scene",
  "stage_data": {
    "target_location": {
      "longitude": 113.9526,
      "latitude": 22.5431,
      "altitude_agl": 80.0
    },
    "current_location": {                  // Device position when it starts flying to the scene
      "longitude": 113.9400,
      "latitude": 22.5500,
      "altitude_alt": 120.0
    },
    "estimated_arrival_sec": 45,           // Estimated arrival time (seconds); null if unavailable
    "estimated_distance_m": 850.0,         // Estimated distance (meters)
    "flight_speed_mode": "normal",         // Flight speed mode: normal
    "vlm_enabled": true                    // Whether multimodal recognition is enabled
  }
}

on_scene (Arrived at the scene):
{
  "stage": "on_scene",
  "stage_data": {
    "actual_location": {                   // Actual arrival coordinates
      "longitude": 113.9527,
      "latitude": 22.5430,
      "altitude_agl": 80.0
    },
    "dispatch_to_scene_sec": 62,           // Total time from dispatch_clicked to arrival at the scene (seconds)
    "takeoff_to_scene_sec": 48,            // Flight time from takeoff to arrival at the scene (seconds)
    "total_actions": 5,                    // Total number of actions (excluding RTH)
    "actions": [                           // Complete action sequence
      { "index": 0, "type": "camera_panaroma_photo_take", "params": {} },
      { "index": 1, "type": "camera_look_at", "params": {} }
    ]
  }
}

returning (Returning to home):
{
  "stage": "returning",
  "stage_data": {
    "return_reason": "mission_complete",   // RTH reason: mission_complete | user_interrupt | false_alarm | low_battery
    "actions_completed": 5,                // Number of completed actions
    "actions_total": 5,                    // Total number of actions
    "estimated_return_sec": 55             // Estimated RTH time (seconds); null if unavailable
  }
}

mission_ended (Mission ended, terminal state):
{
  "stage": "mission_ended",
  "stage_data": {
    "result": "success",                   // Mission result: success | failed | interrupted | cancelled
    "is_false_alarm": false,               // Whether marked as a false alarm (marked in the cockpit)
    "total_duration_sec": 180,             // Total time from dispatch_clicked to mission_ended (seconds)
    "flight_duration_sec": 120,            // Flight time only (seconds)
    "dispatch_to_scene_sec": 62,           // Time from dispatch to arrival at the scene (seconds)
 }

}

media_uploaded (Media files uploaded):
{
  "stage": "media_uploaded",
  "stage_data": {
    "media_summary": {                     // Media statistics for this mission
      "photo_count": 12,
      "video_count": 2,
      "ai_snapshot_count": 1
    },
    "snapshots": {                         // Snapshot summary
      "total": 3,
      "manual_count": 2,                   // Number of manual snapshots
      "ai_alert_count": 1,                 // Number of AI alert snapshots
      "list": [
        {
          "snapshot_id": "snap_20260629_001",
          "sequence": 1,
          "source": "manual",
          "captured_at": "2026-06-29T14:31:20+08:00",
          "image_url": "https://media.dji.com/snap/xxx.jpg",
        },
        {
          "snapshot_id": "snap_20260629_002",
          "sequence": 2,
          "source": "ai_alert",
          "captured_at": "2026-06-29T14:31:45+08:00",
          "image_url": "https://media.dji.com/snap/yyy.jpg",
          "target_type": "vehicle"
        }
      ]
    }
  }
}

Snapshot Events

Sent when Capture Snapshot is clicked in the cockpit. When event_type is snapshot, a snapshot object is added to the common fields. Snapshot events do not affect the lifecycle stage.

{
  "snapshot": {
    "snapshot_id": "snap_20260629_001",
    "source": "manual",                    // Snapshot source: manual (manual capture) | ai_alert (AI alert)
    "sequence": 1,                         // Snapshot sequence number for this alert
    "image": {
      "url": "	xxxx",
      "expires_at": "2026-06-30T14:31:20+08:00",
      "width": 1920,
      "height": 1080,
      "size_bytes": 458000,
      "format": "jpeg"
    },
    "target": {
      "type": "person",                    // Alert target type: person | vehicle | fire | ...
      "type_label": "人",                   // Alert target type name; follows the project's language setting
      "confidence": null,                  // null for manual snapshots; confidence from 0-1 for AI alerts
      "bbox": null                         // null for manual snapshots; normalized [x, y, w, h] for AI alerts
    },
    "capture_context": {
      "current_stage": "on_scene",         // Stage at the time of capture
      "drone_location": {
        "longitude": 113.95260,
        "latitude": 22.54310,
        "altitude_agl": 83.0
      },
      "gimbal_pitch": -45.0,               // Gimbal pitch angle (degrees)
      "zoom_factor": 7.0,                  // Zoom factor
      "camera_type": "payload_wide"        // Lens source
    }
  }
}


Create an Automated Workflow Notification Rule

Click Create in the upper-right corner of the Notification Rule Configuration list and select Automated Workflow.

  • Rule name: Required. Supports a custom rule name.
  • Receiving address: Required. Supports HTTP and HTTPS protocols.
  • Subscription data scope: Select All Projects or Specific Projects.
    • All Projects: Automatically includes all projects created in the future.
    • Specific Projects: Each project can be referenced by only one custom rule (excluding rules for all projects). Projects already referenced are grayed out.
  • Subscribed event types: Automated workflow message notifications.


Delivery Log Auditing

EventAPI provides 7-day delivery log statistics and supports downloading logs from the last 7 days in CSV format. Only data from the last 7 days is retained. The data includes:

  • Success rate: Displayed as a percentage; a 200 callback is considered successful.
  • Total events: Total number of events generated in the last 7 days.
  • Number of failures: Total number of failed deliveries in the last 7 days.
Last Updated: