Register callback endpoint

Article summary

Did you find this summary helpful?

Thank you for your feedback

This is an API to register a callback endpoint that can receive events from Live Station.
Callback endpoints can be used by separating callback settings for all channels and callback settings for individual channels.

Callback delivery data

If you register a callback endpoint, the following data is sent to the set endpoint URL whenever an event occurs in Live Station. (Using HTTP POST)

Callback delivery response body

Field name	Required	Type
id	Yes	String
logLevel	Yes	String
channelId	Yes	String
event	Yes	String
timestamp	Yes	String

Callback delivery response example

{
       "id": 1234,
       "logLevel": "INFO",
       "channelId": "ls-20200327140131-aBCD3",
       "event": "STREAM_UPDATE",
       "timestamp": 1599218791425
}

Request

Endpoint	Description
[POST https://livestation.apigw.ntruss.com/api/v2/events/callbackEndpoint]	Set up global channel callbacks (N (channels): 1 (callback endpoint))
[POST https://livestation.apigw.ntruss.com/api/v2/channels/{channelId}/callbackEndpoint]	Set up general channel-specific callbacks (1 (channel): 1 (callback endpoint))
[POST https://livestation.apigw.ntruss.com/api/v2/re-stream/channels/{channelId}/callbackEndpoint]	Set up restream channel-specific callbacks (1 (channel): 1 (callback endpoint))
[POST https://livestation.apigw.ntruss.com/api/v2/vod/channels/{channelId}/callbackEndpoint]	Set up VOD channel-specific callbacks (1 (channel): 1 (callback endpoint))

Callback delivery action by request

Callback endpoint by channel	Global channel callback endpoint	Action
Not set	Not set	No callback sent
Not set	Set	Send to global channel callback endpoint
Set	Not set	Send to callback endpoints set up for specific channels
Set	Set	Send to callback endpoints set up for specific channels

Request headers

Header name	Required	Description
x-ncp-apigw-timestamp	YES	It indicates the elapsed time in milliseconds since January 1, 1970 00:00:00 UTC. Request is considered invalid if the timestamp differs from the current time by more than 5 minutes `x-ncp-apigw-timestamp:{Timestamp}`
x-ncp-iam-access-key	YES	Access key ID value issued on NAVER Cloud Platform portal `x-ncp-iam-access-key:{Sub Account Access Key}`
x-ncp-apigw-signature-v2	YES	Signature encrypted with the access key ID value and secret key `x-ncp-apigw-signature-v2:{API Gateway Signature}`
x-ncp-region_code	YES	Region code (KR)

Global channel callback setup request body

Field name	Required	Type	Restrictions	Description
callbackUrl	Yes	String	custom endpoint to receive callbacks

Individual channel callback setup request body

Field name	Required	Type	Restrictions	Description
callbackEndpoint	Yes	String	custom endpoint to receive callbacks

Response

Global channel callback setup response

Field name	Type	Description	Remarks
callbackUrl	String
updateTime	Integer

General channel callback setup response

Field name	Type	Description	Remarks
channelId	String
channelName	String
instanceNo	String
qualitySetId	Integer
qualitySetName	String
outputProtocol	String	Default set: HLS, DASH
channelStatus	String	CREATING, READY, PUBLISH, DELETED,BLOCK
isRecording	Boolean
useDvr	Boolean
immediateOnAir	Boolean
timemachineMin	Integer		Unit: Minute
snapshot	Object
snapshotId	Integer
cdn	Object
cdn.instanceNo	String		0 if NO_CDN
cdn.serviceName	String	CDN Service Name	"" if NO_CDN
cdn.profileId	Integer	Profile ID of Global Edge	0 if NO_CDN
cdn.statusName	String	CDN status	"" if NO_CDN
cdn.cdnType	String	GLOBAL_CDN, GLOBAL_EDGE
cdn.cdnDomain	String	CDN Domain	"" if NO_CDN
record	Object
record.format	String	MP4, HLS, ALL
record.type	String	NO_RECORD, AUTO_UPLOAD, MANUAL_UPLOAD
record.bucketName	String
record.filePath	String
record.accessControl	String	PRIVATE, PUBLIC_READ
publishUrl	String
streamKey	String
recentPublishStartTime	Integer
createdTime	Integer
alertOn	Boolean		if alertOn == true, alertOptions should be set
alertOptions	Object
alertOptions.alertChangeStatus	Boolean
alertOptions.alertVodUploadFail	Boolean
alertOptions.alertReStreamFail	Boolean
totalPublishSeconds	Integer
envType	String	DEV, STAGE, REAL
callbackEndpoint	String

Restream channel callback setup response

Field name	Type	Description	Remarks
channelId	String
channelName	String
instanceNo	Integer
channelStatus	String
createdTime	Integer
publishUrl	String
streamKey	String
planType	String	STANDARD, PROFESSIONAL
restream	Object[]
restream[].targetName	String
restream[].rtmpUrl	String
restream[].streamKey	String
restream[].id	String		Displayed when set
restream[].password	String	Displayed when set
platformCount	Integer
totalPublishSeconds	Integer
recentPublishStartTime	Integer
alertOn	Boolean
alertOptions	Object
alertOptions.alertChangeStatus	Boolean
alertOptions.alertVodUploadFail	Boolean
alertOptions.alertReStreamFail	Boolean
isPublishing	Boolean
envType	String	DEV, STAGE, REAL
callbackEndpoint	String

Examples

Global channel callback setup request example

POST /api/v2/events/callbackEndpoint
HOST: livestation.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=
x-ncp-region_code:KR

{
  "callbackUrl": "https://my-callback-endpoint"
  }

Global channel callback setup response example

HTTP/1.1 200 OK
Server: nginx
Date: Wed, 12 Sep 2018 09:53:32 GMT
Content-Type: application/json;charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: *
x-ncp-trace-id: 36c9k60om4p3238cpmc9gm4cj4

{
   "content": {
      "callbackUrl": "https://my-callback-endpoint",
      "updateTime": 1614751615488
   }
}

General channel-specific callback setup request example

POST /api/v2/channels/{channelId}/callbackEndpoint
HOST: livestation.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=
x-ncp-region_code:KR

{
  "callbackEndpoint": "https://my-callback-endpoint"
}

General channel-specific callback setup response example

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 26 Sep 2021 09:53:32 GMT
Content-Type: application/json;charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: *
x-ncp-trace-id: 36c9k60om4p3238cpmc9gm4cj4

{
    "content" : {
        "channelId" : "ls-20200323114720-bMoDF",
        "channelName" : "mychannel",
        "instanceNo" : 1163899,
        "qualitySetId" : 6,
        "qualitySetName" : "360p-set",
        "outputProtocol" : "HLS, DASH",
        "channelStatus" : "READY",
        "isRecording" : false,
        "useDVR" : true,
        "immediateOnAir" : false,
        "timemachineMin" : 360,
        "cdn" : {
            "instanceNo" : "1163900",
            "serviceName" : "edge-ls-20200323114720-bMoDF",
            "statusName" : "RUNNING",
            "cdnType" : "GLOBAL_EDGE",
            "cdnDomain" : "mycdn.edge.naverncp.com",
             "profileId": 299,
             "regionType": "KOREA"
        },
        "record": {
            "type": "AUTO_UPLOAD",
            "bucketName": "hls",
            "filePath": "/livestation",
            "format": "MP4",
            "accessControl": "PRIVATE"
       },
        "publishUrl": "rtmp://live-station-rtmp-url",
        "streamKey": "jjiantco4psakuwd5526u2glcxrqaar4",
        "totalPublishSeconds" : 0,
        "createdTime" : 1584931640000,
        "recentPublishStartTime": 0,
        "alertOn" : false,
        "alertOptions" : {
            "alertChangeStatus" : false,
            "alertVodUploadFail" : false,
            "alertReStreamFail" : false
        },
        "callbackEndpoint": "https://my-callback-endpoint",
        "envType": "REAL"
    }
}

Restream channel-specific callback setup request example

POST /api/v2/re-stream/channels/{channelId}/callbackEndpoint
HOST: livestation.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=
x-ncp-region_code:KR

{
  "callbackEndpoint": "https://my-callback-endpoint"
}

Restream channel-specific callback setup response example

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 26 Feb 2021 09:53:32 GMT
Content-Type: application/json;charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: *
x-ncp-trace-id: 36c9k60om4p3238cpmc9gm4cj4

{
  "content": {
    "channelId": "ls-20210225185132-FxGSn",
    "channelName": "mycallback-20210225185132",
    "instanceNo": 1627140,
    "channelStatus": "READY",
    "streamKey": "7xtotpxpkjnyhmjbe7k7jaa952q6lmhl",
    "publishUrl": "rtmp://live-station-rtmp-url",
    "planType": "STANDARD",
    "createdTime": 1614246692000,
    "restream": [
      {
        "id": "itis",
        "rtmpUrl": "rtmp://notworking-just-testcase.only",
        "streamKey": "12345",
        "password": "itispassword",
        "targetName": "YOUTUBE"
      }
    ],
    "platformCount": 1,
    "totalPublishSeconds": 0,
    "alertOn": false,
    "isPublishing": false,
    "alertOptions": {
      "alertChangeStatus": false,
      "alertVodUploadFail": false,
      "alertReStreamFail": false
    },
    "callbackEndpoint": "https://my-callback-endpoint",
    "envType": "REAL"
  }
}

VOD channel-specific callback setup response example

{
  "content": {
    "channelId": "ls-20211122220557-mUv3r",
    "channelName": "mycallback-20211235185132",
    "instanceNo": 2043025,
    "qualitySetId": 4,
    "qualitySetName": "720p-set",
    "outputProtocol": "HLS",
    "status": "READY",
    "cdn": {
      "instanceNo": "1541959",
      "serviceName": "edge-ls-20201204112949-D7RTL",
      "statusName": "RUNNING",
      "cdnType": "GLOBAL_EDGE",
      "cdnDomain": "mycdn.edge.naverncp.ntruss.com",
      "profileId": 299,
      "regionType": "KOREA"
    },
    "totalPublishSeconds": 0,
    "createdTime": 1637586357000,
    "updatedTime": 1637587476000,
    "alertOn": false,
    "alertOptions": {
      "alertChangeStatus": false
    },
    "callbackEndpoint": "https://my-callback-endpoint",
    "envType": "REAL",
    "type": "VOD",
  }
}

Was this article helpful?

What's Next

Live Station error codes

Table of contents

Callback delivery data
Request
Response
Examples