Pulled-stream relay callbacks

Pulled-stream relay callbacks notify your application when a task changes state or exits. This topic covers the trigger conditions and sample callback payloads.

Callback events

Pulled-stream relay callbacks cover two types of events: task state changes and task exits.

A pulled-stream relay task can have one of the following states:

State	Description
Idle	The initial state of a task created by an API call.
Running	The state when a task starts at its scheduled time or is restarted by an API call.
Recovering	The state when a task is retrying after an execution error.
Offline	The state after a task stops because retry attempts time out or an API call stops it.
Exit	The state after a task is deleted, either when its scheduled end time is reached or by an API call.

Callback for task state changes

Description

A callback is triggered when a pulled-stream relay task transitions to Running, Recovering, or Offline.

Trigger conditions

The task transitions to Running when it starts at its scheduled start time or is restarted by an API call.
The task transitions to Recovering when it encounters an error during execution.
The task transitions to Offline when an API call stops it or its retry attempts time out.

Callback for task exit

Description

A callback is triggered when a pulled-stream relay task exits. An exit means the system has removed the expired task.

Trigger conditions

The task transitions to Exit when the system deletes it because its scheduled end time is reached.
The task transitions to Exit when an API call deletes it.

Callback payload

The callback is sent as a JSON object in the request body of an HTTP POST request to your callback URL. Parse the request body to retrieve the callback content.

Parameters and sample payload for a task state change callback

Table 1. Callback payload for task state changes

Parameter	Description
Event	The event name. Fixed value: `LivePullToPushRunning`.
EventTime	The time when the event occurred, as a Unix timestamp in seconds.
TaskId	The task ID.
TaskInfo	The task information.
TaskStatus	The current state of the task. Valid values: 1: Running 2: Recovering 3: Offline
TaskInvalidReason	The reason the task ran abnormally or stopped. Valid values: `PullStreamFailed`: Failed to pull the stream. `PushStreamFailed`: Failed to relay the stream. `TriggerByUser`: Stopped by an API call. `UnknownError`: An unknown error occurred. `RetryTimesOffline`: Retry attempts timed out. Note This parameter is returned only when the task state is `Offline`.

Sample payload

{
"Event": "LivePullToPushRunning",
"EventTime": "1725501246",
"TaskId": "08a1b00c-9c2f-4dfa-9f5d-878f2505****",
"TaskInfo": {
    "TaskId": "08a1b00c-9c2f-4dfa-9f5d-878f2505****",
    "StartTime": "2024-09-05T01:54:00Z",
    "EndTime": "2024-09-05T01:58:00Z",
    "SourceUrls": [
      "\"http://fyl-*******-*****.oss-cn-beijing.aliyuncs.com/record/caster/741584e2557248e98ef332d41e4afc3d/2024-08-30-18:19:40_2024-08-30-18:21:09.mp4\""
    ],
    "DstUrl": "rtmp://pushtest.******.aliyunlive.com/pulltest38/pulltest-w38",
    "CallbackURL": "https://1833220977******.cn-shanghai.lc.aliyuncs.com/workflows/lc-uf6sd1382ikolc/triggers/manual/methods/invoke?ApiVersion=2018-12-12&Signature=TZT7CGDgc299cC2dtL73Yeq4xY8",
    "Offset": 0,
    "SourceType": "url"
  },
"TaskStatus": "1"
}

Parameters and sample payload for a task exit callback

Table 2. Callback payload for task exit

Parameter	Description
Event	The event name. Fixed value: `LivePullToPushExit`.
EventTime	The time when the event occurred, as a Unix timestamp in seconds.
TaskId	The task ID.
TaskInfo	The task information.
TaskStatus	The current state of the task. Valid value: -1: Exit
TaskExitTime	The time when the task exited, as a Unix timestamp in seconds.
TaskExitReason	The reason the task exited. Valid values: `TriggerByUser`: Deleted by an API call. `OverEndTime`: The scheduled end time was reached.

Sample payload

{
  "Event": "LivePullToPushExit",
  "EventTime": "1725501483",
  "TaskId": "08a1b00c-9c2f-4dfa-9f5d-878f2505****",
  "TaskInfo":  {
    "TaskId": "08a1b00c-9c2f-4dfa-9f5d-878f2505****",
    "StartTime": "2024-09-05T01:54:00Z",
    "EndTime": "2024-09-05T01:58:00Z",
    "SourceUrls": [
      "\"http://fyl-******-****.oss-cn-beijing.aliyuncs.com/record/caster/741584e2557248e98ef332d41e4afc3d/2024-08-30-18:19:40_2024-08-30-18:21:09.mp4\""
    ],
    "DstUrl": "rtmp://pushtest.*****.aliyunlive.com/pulltest38/pulltest-w38",
    "CallbackURL": "https://1833220977******.cn-shanghai.lc.aliyuncs.com/workflows/lc-uf6sd1382ikolc/triggers/manual/methods/invoke?ApiVersion=2018-12-12&Signature=TZT7CGDgc299cC2dtL73Yeq4xY8",
    "Offset": 0,
    "SourceType": "url"
  },
  "TaskStatus": "-1",
  "TaskExitTime": "1725501483",
  "TaskExitReason": "OverEndTime",
}