Skip to main content
The hook system allows you to automatically execute device actions in response to specific events in the media processing pipeline. Hooks can be device-specific or global.

​
Hook event types

The Studio service supports 7 different hook event types:
  1. after_event_pulled - After an event is successfully pulled from device
  2. after_all_events_pulled - After all events in a batch are processed
  3. after_event_processed - After an event is processed and stored
  4. after_thumbnail_generated - After a thumbnail is generated for an event
  5. on_file_detected - When a new file is detected in the incoming directory
  6. on_error - When an error occurs during processing
  7. on_service_start - When the media service starts for a device

​
List hooks

GET /api/hooks

List all hooks with optional device filtering

​
Query parameters

​
deviceId
string
Filter hooks by device ID. Omit to get all hooks.

​
Response

Returns an array of hook objects.
​
id
string
required
Unique hook identifier
​
event
string
required
Hook event type
​
action
string
required
Action name to execute
​
deviceId
string
Device ID for device-specific hooks, or null for global hooks
​
enabled
boolean
required
Whether the hook is active
​
parameters
object
Parameters to pass to the action

​
Example request

curl "http://localhost:8001/api/hooks?deviceId=device123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
[
  {
    "id": "hook_abc123",
    "event": "after_event_pulled",
    "action": "process-event",
    "deviceId": "device123",
    "enabled": true,
    "parameters": {
      "quality": "high"
    }
  }
]

​
Create hook

POST /api/hooks

Create a new event hook

​
Request body

​
event
string
required
Hook event type. Must be one of the 7 supported event types.
​
action
string
required
Name of the action to execute when the event occurs
​
deviceId
string
Device ID for device-specific hook. Omit for global hook that applies to all devices.
​
enabled
boolean
default:true
Whether the hook is active
​
parameters
object
Parameters to pass to the action. Supports template variables.

​
Response

​
id
string
required
ID of the created hook
​
success
boolean
required
Indicates if creation was successful

​
Example: Create device-specific hook

curl -X POST "http://localhost:8001/api/hooks" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "after_event_pulled",
    "action": "remove-event",
    "deviceId": "device123",
    "enabled": true,
    "parameters": {
      "event_name": "{{event_name}}"
    }
  }'
Response: 
{
  "success": true,
  "id": "hook_xyz789"
}

​
Example: Create global hook

curl -X POST "http://localhost:8001/api/hooks" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "on_error",
    "action": "send-alert",
    "enabled": true,
    "parameters": {
      "severity": "error",
      "message": "Media processing error on {{device_id}}"
    }
  }'

​
Update hook

PATCH /api/hooks/:id

Update an existing hook

​
Path parameters

​
id
string
required
Hook identifier

​
Request body

​
event
string
Hook event type
​
action
string
Action name to execute
​
enabled
boolean
Whether the hook is active
​
parameters
object
Parameters to pass to the action

​
Response

​
success
boolean
required
Indicates if update was successful

​
Example request

curl -X PATCH "http://localhost:8001/api/hooks/hook_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
Response: 
{
  "success": true
}

​
Delete hook

DELETE /api/hooks/:id

Delete a hook

​
Path parameters

​
id
string
required
Hook identifier

​
Response

​
success
boolean
required
Indicates if deletion was successful

​
Example request

curl -X DELETE "http://localhost:8001/api/hooks/hook_abc123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "success": true
}

​
Get hooks by event type

GET /api/hooks/events/:eventType

Get all hooks for a specific event type

​
Path parameters

​
eventType
string
required
Event type to filter by

​
Response

Returns an array of hook objects matching the event type.

​
Example request

curl "http://localhost:8001/api/hooks/events/after_event_pulled" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
[
  {
    "id": "hook_abc123",
    "event": "after_event_pulled",
    "action": "remove-event",
    "deviceId": "device123",
    "enabled": true,
    "parameters": {
      "event_name": "{{event_name}}"
    }
  },
  {
    "id": "hook_def456",
    "event": "after_event_pulled",
    "action": "process-video",
    "deviceId": "device456",
    "enabled": true,
    "parameters": {}
  }
]

​
Parameter templating

Hook parameters support dynamic template variables that are automatically replaced with context values:
  • {{device_id}} - Current device ID
  • {{event_name}} - Event filename
  • {{media_type}} - Media type (image, video, audio, etc.)
  • {{file_path}} - Full file path
  • {{timestamp}} - Current timestamp
  • {{date}} - Current date in YYYY-MM-DD format

​
Example with templates

{
  "event": "after_event_pulled",
  "action": "process-event",
  "parameters": {
    "input": "{{file_path}}",
    "output": "/processed/{{device_id}}/{{event_name}}",
    "date": "{{date}}"
  }
}
When executed, templates are replaced: 
{
  "input": "/data/gallery/device123/processed/video.mp4",
  "output": "/processed/device123/video.mp4",
  "date": "2024-03-20"
}

​
Hook execution flow

  1. Event occurs - Media processing triggers an event
  2. Hook lookup - System finds all enabled hooks for the event type
  3. Device filtering - Applies device-specific and global hooks
  4. Parameter injection - Replaces template variables with actual values
  5. Action execution - Calls the configured action with parameters
  6. Error handling - Logs failures but doesn’t interrupt processing

Build docs developers (and LLMs) love

Get started for freeTalk to us