Webhook reference
Enable webhooks by going to settings.ini file in SAMMI folder and adding the following keys:
open_server = 1
server_port = <your selected localhost port>
(default = 9450)
The server will start running as soon as SAMMI is launched.
As of now it only supports POST requests to the /webhook
endpoint.
Webhook trigger can be only added if developer mode is enabled
Url: http://localhost:<server_port>/webhook
(default = http://localhost:9450/webhook
)
Headers: Not required, authorization will be added later.
Body: Plain text or JSON
SAMMI accepts body in the following formats:
-
Plain text = sends a webhook trigger with
webhook
as message and data as plain textExample Request:
Hi there
Response:
{ "data": "Ok. No proper JSON found, webhook trigger sent with plain text data." }
-
JSON:
- With
trigger
value = sends a webhook trigger with thetrigger
value as message anddata
as data object
Example Request:
{ "trigger": "My webhook trigger", "data": "Hello World" }
Response:
{ "data": "Ok. Webhook trigger sent." }
- With
request
object = will perform the specified request (see examples below)
- With
Available Requests
triggerButton
buttonID
= ID of the button you wish to trigger
Example Request:
{
"request": "triggerButton",
"data": {
"buttonID": "ID16"
}
}
Response:
{
"data": "Ok."
}
releaseButton
buttonID
= ID of the button you wish to release
Example Request:
{
"request": "releaseButton",
"data": {
"buttonID": "ID16"
}
}
Response:
{
"data": "Ok."
}
modifyButton
buttonID
= ID of the button you wish to modify
id
- button ID to modify
color
- decimal button color (BGR)
text
- button text
image
- button image file name
border
- border size, 0-7
leave parameters empty to reset button back to default values
Example Request:
{
"request": "modifyButton",
"data": {
"buttonID": "ID13",
"text": "Hello World",
"border": 2
}
}
Response:
{
"data": "Ok."
}
popupMessage
message
= text to show
Example Request:
{
"request": "popupMessage",
"data": {
"message": "Hello World!"
}
}
Response:
{
"data": "Ok."
}
alertMessage
message
= text to show
Example Request:
{
"request": "alertMessage",
"data": {
"message": "Hello World!"
}
}
Response:
{
"data": "Ok."
}
notificationMessage
title
= title for the tray message
message
= text to show
Example Request:
{
"request": "notificationMessage",
"data": {
"title": "My Webhook",
"message": "Hello World!"
}
}
Response:
{
"data": "Ok."
}
getVariable
buttonID
= button ID where the variable lives, use “global” for global variables
name
= name of the variable to retrieve
Example Request for a regular variable:
{
"request": "getVariable",
"data": {
"buttonID": "ID16",
"name": "myVariable"
}
}
Response:
{
"data": "Test Hello" // this is the value of the `myVariable` variable
}
Example Request for an object:
{
"request": "getVariable",
"data": {
"buttonID": "ID16",
"name": "myObject"
}
}
Response:
{
"data": "{
"value
": {
"key
":
"bla
" } }" // this is the stringified object 'myObject'
}
setVariable
buttonID
= button ID where the variable will live, use “global” for global variables
name
= name of the variable to set
value
= variable value
Example Request for setting a regular string variable:
{
"request": "setVariable",
"data": {
"buttonID": "ID16",
"name": "myVariable",
"value": "Hi there!"
}
}
Response:
{
"data": "Ok."
}
Example Request for setting a new object variable:
{
"request": "setVariable",
"data": {
"buttonID": "ID16",
"name": "myObject",
"value": {
"firstKey": "Hi there",
"secondKey": "Hello there"
}
}
}
Response:
{
"data": "Ok."
}
deleteVariable
buttonID
= button ID where the variable lives, use “global” for global variables
name
= name of the variable to delete
Example Request:
{
"request": "deleteVariable",
"data": {
"buttonID": "ID16",
"name": "myVariable",
}
}
Response:
{
"data": "Ok."
}
insertArray
buttonID
= button ID where the array lives, use “global” for global variables
name
= name of the array to insert the value into
index
= index (position) in the array to insert the value into, first position has an index 0
value
= value to insert
Example Request:
{
"request": "insertArray",
"data": {
"buttonID": "ID16",
"name": "myArray",
"index": 1,
"value": "Hello World"
}
}
Response:
{
"data": "Ok."
}
deleteArray
buttonID
= button ID where the array lives, use “global” for global variables
name
= name of the array to delete the index in
index
= index (position) in the array to delete, the first position has index of 0
Example Request:
{
"request": "deleteArray",
"data": {
"buttonID": "ID16",
"name": "myArray",
"index": 0,
}
}
Response:
{
"data": "Ok."
}
Command Line
You can perform all the requests above from Command Line by using curl
.
Example curl request for json formatted body:
curl -d "{
"someValue
":
"Hello World!
",
"trigger
":
"some trigger
"}" -X POST http://localhost:9450/webhook
The some trigger
trigger will be the webhook trigger message.
Example curl request for text formatted body:
curl -d "yay" -X POST http://localhost:9450/webhook
If there’s no trigger found, the webhook trigger message will be automatically set to “webhook”.
Errors
SAMMI will respond with status 404 if the request does not exist or it is missing required data
Example of sending misspelled request:
{
"request": "triggerrButton",
"data": {
"buttonID": "ID16",
}
}
Response (404):
{
"data": "Unknown request. Send Webhook trigger instead. See protocol for all documented requests."
}
Example of sending correct request with missing required data:
{
"request": "setVariable",
"data": {
"buttonID": "ID16"
}
}
Response (404):
{
"data": "Set Variable request is missing Data object: {name, value, buttonID}."
}