Hooks

Hooks allow other apps and programs to be notified when actions occur within the OnSong app.

List hooks

URL/api/<auth_token>/hooks
MethodGET
Version1.0

Description

Lists current hooks managed by this OnSong instance.

Path arguments

Name Type Description Required
auth_token string The authentication token used to authenticate the request. Required

Response

Returns an array of hooks that will be called when actions are performed.

Response example

[
  {
    "name" : "Stage iPad",
    "endpoint" : "http://10.1.0.100/api/<auth_token>/hooks"
  },
  {
    "name" : "Soundroom Projection",
    "endpoint" : "http://10.1.0.234/another/app/onsong/hooks"
  }
]

Create hook

URL/api/<auth_token>/hooks
MethodPUT
Version1.0

Description

Creates a new hook which will be called when an event occurs within the API's instance of OnSong.

Path arguments

Name Type Description Required
auth_token string The authentication token used to authenticate the request. Required

Body arguments

Name Type Description Required
name string The name of the device or service that will be added. This is usually the name of the device and app requesting access. Required
endpoint url This is the URL where OnSong will POST change information for the API's instance of OnSong. Required
model string The model of the device that is being registered. Optional

Response

Returns a basic response code to determine the success or failure of the operation.

Response example

{
  "success" : {
    "name" : "Soundroom Projection", 
    "endpoint" : "http://10.1.0.234/another/app/onsong/hooks"
  }
}

Call hook

URL/api/<auth_token>/hooks
MethodPOST
Version1.0

Description

This method receives any events from the API's OnSong instance and forwards them to the proper notifications.

Path arguments

Name Type Description Required
auth_token string The authentication token used to authenticate the request. Required

Body arguments

Name Type Description Required
name string The name of the notification send from the OnSong instance. Required
userInfo object This is an object containing specific information about the forwarded event. Required

Body example

{
  "name" : "SectionWasAdjusted",
  "userInfo" : {
    "amount" : 0.3333
  }
}

Response

Returns a basic response code to determine the success or failure of the operation.

Response example

{
  "success" : "Hook has been registered"
}

Delete hook

URL/api/<auth_token>/hooks
MethodDELETE
Version1.0

Description

This method deletes the specified hook.

Path arguments

Name Type Description Required
auth_token string The authentication token used to authenticate the request. Required

Body arguments

Name Type Description Required
endpoint string The endpoint to be removed from the OnSong instance. This will prevent further notifications from being forwarded. Required

Body example

{
  "endpoint" : "http://10.1.0.234/another/app/onsong/hooks"
}

Response

Returns a basic response code to determine the success or failure of the operation.

Response example

{
  "success" : "Hook deleted"
}