Studio Server Webhook events

Info: This feature requires Studio Server 10.13 or higher.

Webhooks have been added as a feature of Studio Server 10.13 to enable 3rd-party applications to receive and then act upon events that take place in the Studio Server system.

The events that can be used for Studio Server are described here in this article.

Resources

To learn more about Studio Server Webhooks, use the following resources:

• The Webhooks section of the Web Services Guide for Studio Server.
• The Studio Server Web Services SDK (see http://your Studio Server URL/StudioServer/server/plugins/Webhooks/sdk/doc/interfaces/registration.htm)
• For the examples in this article, Postman was used to send calls and receive responses.

Requirements

Using Studio Server Webhooks requires Studio Server 10.13 or any higher version of Studio Server.

The WflMultiSetObjectProperties service for capturing metadata changes to multiple objects simultaneously requires Studio Server 10.57.0 or higher. To receive the events, the 'com.woodwing.studio/object/properties-updated' event type must be registered.

Configuration

The following configuration is needed to use Studio Server Webhooks:

• Webhooks enabled:
• On the Server Plug-ins Maintenance page of Studio Server, check to see that the ‘Webhooks’ Server plug-in is installed and enabled.
• RabbitMQ integrated.
• Cron jobs to trigger the RabbitMQ ‘event bus’ and to fire the events to the endpoint:
• http://localhost/StudioServer/eventbusindex.php?exchangename=eventbus
• http://localhost/StudioServer/eventbusindex.php?exchangename=webhook

Note: The default time for the RabbitMQ process to run is 60 seconds. If you want them to run longer (or shorter) use the '@maxexectime' parameter.

Example: http://localhost/StudioServer/eventbusindex.php?exchangename=webhook@maxexectime=120 will run for 2 minutes.

Available service calls

Supported object events

The following object events within Studio Server are supported:

Examples

Example 1. Logging on to Studio Server

In this example, a log on request is done to log on to Studio Server with valid credentials to get a ‘ticket’ that will be used in the subsequent calls to the endpoint.

The endpoint to send this request to will be something like:

http://localhost:81/StudioServer/index.php?protocol=JSON

Request

Copy the code

{
	"method": "LogOn",
	"id": "1",
	"params": {
		"req": {
			"User": "your user name",
			"Password": "your password",
			"ClientName": "postman",
			"ClientAppName": "postman_sample_requests",
			"__classname__": "WflLogOnRequest"
		}
	},
	"jsonrpc": "2.0"
}

Note: The above call is using example values for 'User”, 'Password”, 'ClientName'and 'ClientAppName'. Change the values being sent to what is appropriate for your system.

Response

{
    "id": "1",
    "result": {
        "Ticket": "e08d86e5day6tiSYTRJXtHHsXSnak97bmYIDY4os",
        "Publications": [
            {
                "Id": "1",
                "Name": "WW News",
                "Issues": null,
...
}

Note: The response in this case is truncated to show just the ticket and the first part of the ‘Publications’ information. See the Web Services Guide and the Web Services SDK information located within Studio Server for more information.

Example 2: Listing events that can be used to trigger sending a Webhook

In this example, a list of available events which can be used to trigger sending a Webhook is requested.

This is done by using the GetTriggerOptions call.

The endpoint to send this request to will be something like this:

http://localhost:81/StudioServer/pluginindex.php?plugin=Webhooks&interface=reg&protocol=JSON

Request

Copy the code

{
	"jsonrpc":"2.0",
	"method":"GetTriggerOptions",
	"params": {
		"req": {
			"Ticket": "",
			"__classname__": "WhRegGetTriggerOptionsRequest"
		}
	},
	"id":1
}

Response

Note: The response lists all of the ‘EventTypes’ available for Studio Server Webhooks. For more information see the Web Services guide, section Webhooks.

{
    "id": "1",
    "result": {
        "Options": [
            {
                "Entity": {
                    "Name": "object",
                    "DisplayName": "Object",
                    "__classname__": "WhRegEntity"
                },
                "EventTypes": [
                    {
                        "Name": "com.woodwing.studio/object/created",
                        "DisplayName": "Object Created",
                        "__classname__": "WhRegEventType"
                    },
                    {
                        "Name": "com.woodwing.studio/object/deleted",
                        "DisplayName": "Object Moved to Trash Can",
                        "__classname__": "WhRegEventType"
                    },
                    {
                        "Name": "com.woodwing.studio/object/deleted-permanently",
                        "DisplayName": "Object Deleted Permanently",
                        "__classname__": "WhRegEventType"
                    },
                    {
                        "Name": "com.woodwing.studio/object/restored",
                        "DisplayName": "Object Restored",
                        "__classname__": "WhRegEventType"
                    },
                    {
                        "Name": "com.woodwing.studio/object/copied",
                        "DisplayName": "Object Copied",
                        "__classname__": "WhRegEventType"
                    },
                    {
                        "Name": "com.woodwing.studio/object/saved",
                        "DisplayName": "Object Saved",
                        "__classname__": "WhRegEventType"
                    },
                    {
                        "Name": "com.woodwing.studio/object/properties-updated",
                        "DisplayName": "Object Properties Updated",
                        "__classname__": "WhRegEventType"
                    }
                ],
                "__classname__": "WhRegTriggerOptions"
            }
        ],
        "__classname__": "WhRegGetTriggerOptionsResponse"
    },
    "jsonrpc": "2.0"
}

Example 3: Listing already existing Webhooks

In this example, a listing of the already existing Webhooks is obtained.

This is done by using the ListWebhookRegistrations call.

Request

Copy the code

{
    "jsonrpc":"2.0",
    "method":"ListWebhookRegistrations",
    "params": {
		"req": {
			"Ticket": "e08d86e5day6tiSYTRJXtHHsXSnak97bmYIDY4os",
			"__classname__": "WhRegListWebhookRegistrationsRequest"
		}
	},
	"id":1
}

Response

{
    "id": "1",
    "result": {
        "Registrations": [
            {
                "Id": 3,
                "Name": "Workato_1882995",
                "__classname__": "WhRegWebhookRegistration"
            }
        ],
        "__classname__": "WhRegListWebhookRegistrationsResponse"
    },
    "jsonrpc": "2.0"
}

Example 4: Registering a Webhook

In this example, a Webhook is registered.

This is done by using the GetTriggerOptions call.

The endpoint to send this request to will be something like this:

http://localhost:81/StudioServer/pluginindex.php?plugin=Webhooks&interface=reg&protocol=JSON

Request

Copy the code

{
    "method": "CreateWebhookRegistration",
    "id": "",
    "params": [
        {
            "Ticket": "e08d86e5day6tiSYTRJXtHHsXSnak97bmYIDY4os",
            "Registration": {
                "Name": "JeffGapp-Webhook",
                "Url": "https://www.jeffgapp.com/webhooks/index.php",
                "SecretToken": null,
                "Triggers": [
                    {
                        "EntityName": "object",
                        "EventTypes": [
                            "com.woodwing.studio\/object\/created"
                        ],
                        "__classname__": "WhRegTrigger"
                    }
                ],
                "__classname__": "WhRegWebhookRegistrationInfo"
            },
            "__classname__": "WhRegCreateWebhookRegistrationRequest"
        }
    ],
    "jsonrpc": "2.0"
}

Note: As always, replace the ‘Ticket’, 'Name'and 'Url' with values appropriate to your configuration. You can provide a 'SecretToken’ or, by sending a null value, Studio Server will return a token that it generates for you.

Response

{
    "id": "",
    "result": {
        "Registration": {
            "Id": 5,
            "Name": "JeffGapp-Webhook",
            "Url": "https://www.jeffgapp.com/webhooks/index.php",
            "SecretToken": "f65b957c-f3e3-988a-8be5-56ddba21c41f",
            "Triggers": [
                {
                    "EntityName": "object",
                    "EventTypes": [
                        "com.woodwing.studio/object/created"
                    ],
                    "__classname__": "WhRegTrigger"
                }
            ],
            "__classname__": "WhRegWebhookRegistrationInfo"
        },
        "__classname__": "WhRegCreateWebhookRegistrationResponse"
    },
    "jsonrpc": "2.0"
}

Note: As noted above, if you leave the ‘SecretToken’ parameter empty on the request, Studio Server returns a SecretToken value in 8-4-4-4-12 format. Be sure to securely store the ‘SecretToken’ along with the ‘Name’ and ‘Id’ values. You’ll need the ‘Id' to delete the Webhook.

Example 5: Deleting a Webhook

In this example, a Webhook is deleted.

Webhooks can only be deleted by passing the ‘Id' that was returned when the Webhook was created. You can search for a Webhook by using ‘GetWebhookRegistrationRequest ' and including the 'Id’ of the Webhook in the request.

The endpoint to send this request to will be something like this:

http://localhost:81/StudioServer/pluginindex.php?plugin=Webhooks&interface=reg&protocol=JSON

Request

Copy the code

{
    "method": "DeleteWebhookRegistration",
    "id": "",
     "params": [
        {
            "Ticket": "e08d86e5day6tiSYTRJXtHHsXSnak97bmYIDY4os",
            "Id": 6,
            "__classname__": "WhRegDeleteWebhookRegistrationRequest"
        }
     ],
     "jsonrpc": "2.0"
}

Response

{
    "id": "",
    "result": {
        "__classname__": "WhRegDeleteWebhookRegistrationResponse"
    },
    "jsonrpc": "2.0"
}

Example 6: Getting Information about a specific existing Webhook

In this example information about a specific Webhook is requested using the ‘GetWebhookRegistrationRequest’. When making this call, provide the ‘Id’ of the Webhook.

Request

Copy the code

{
    "jsonrpc":"2.0",
    "method":"GetWebhookRegistration",
    "params": {
        "req": {
            "Ticket": "{{Current_Ticket}}",
            "Id": 47,
            "__classname__": "WhRegGetWebhookRegistrationRequest"
        }
    },
    "id":1
}

Response

{
    "id": "1",
    "result": {
        "Registration": {
            "Id": 47,
            "Name": "SendWhenObjectCreated",
            "Url": "https://www.jeffgapp.net",
            "SecretToken": null,
            "Triggers": [
                {
                    "EntityName": "object",
                    "EventTypes": [
                        "com.woodwing.studio/object/created"
                    ],
                    "__classname__": "WhRegTrigger"
                }
            ],
            "__classname__": "WhRegWebhookRegistrationInfo"
        },
        "__classname__": "WhRegGetWebhookRegistrationResponse"
    },
    "jsonrpc": "2.0"
}

Example 7: Updating an existing Webhook

In this example information about a specific Webhook is requested using the ‘UpdateWebhookRegistration'. Provide the ‘Id’ of the Webhook you want to update and the parameters to be updated.

In the example below, the ‘Url’ value of the Webhook is updated.

Request

Copy the code

{
    "jsonrpc":"2.0",
    "method":"UpdateWebhookRegistration",
    "params": [
        {
            "Ticket": "{{Current_Ticket}}",
            "Registration": {
                "Id": 47,
                "Name": "SendWhenObjectCreated",
                "Url": "https://www.jeffgapp.net",
                "SecretToken": null,
                "Triggers": [
                    {
                        "EntityName": "object",
                        "EventTypes": [
                            "com.woodwing.studio\/object\/created"
                        ],
                        "__classname__": "WhRegTrigger"
                    }
                ],
                "__classname__": "WhRegWebhookRegistrationInfo"
            },
            "__classname__": "WhRegCreateWebhookRegistrationRequest"
        }
    ],
    "jsonrpc": "2.0"
}

Response

1

To confirm that change beyond the above response, use the 'GetWebhookRegistrationRequest’ call to confirm the new value.

Data that is sent

If you are initially testing the functionality of Studio Webhooks, then there are many tools that can receive a Webhook. In this case we used Webhook.site. The site will create an endpoint and nicely display the incoming data.

Keep in mind that the raw content of the Post includes the data for the Webhook. If you want to validate where the Webhook is coming from, get the ‘x-hook-signature' value from the header and compare that value against the ‘SecretToken' value.

The following data comes from a Webhook. It includes the standard metadata field for Studio Server, custom metadata fields and ‘Target’ metadata fields for the object.

Note: If you are not seeing the Webhook data appear, check that your cron jobs are firing. You can also fire the cron jobs from a terminal application if you like.

{
  "id": "urn:uuid:c67a74cb-d158-3f61-fc4c-7ed91c7de6d2",
  "source": "urn:uuid:2287b041-2f92-3eee-e09d-9324d3bf648a",
  "specversion": "1.0",
  "type": "com.woodwing.studio/object/properties-updated",
  "datacontenttype": "application/json",
  "subject": "object",
  "time": "2021-12-01T19:28:11Z",
  "data": {
    "Object": {
      "MetaData": {
        "BasicMetaData": {
          "ID": "8",
          "DocumentID": "",
          "Name": "Test 1",
          "Type": "Dossier",
          "Publication": {
            "Id": "1",
            "Name": "WW News"
          },
          "Category": {
            "Id": "1",
            "Name": "News"
          },
          "ContentSource": "",
          "MasterId": "0",
          "StoryId": ""
        },
        "RightsMetaData": {
          "CopyrightMarked": false,
          "Copyright": "",
          "CopyrightURL": ""
        },
        "SourceMetaData": {
          "Credit": "",
          "Source": "",
          "Author": ""
        },
        "ContentMetaData": {
          "Description": "",
          "DescriptionAuthor": "",
          "Keywords": [],
          "Slugline": "",
          "Format": "",
          "Columns": "0",
          "Width": "0",
          "Height": "0",
          "Dpi": "0",
          "LengthWords": "0",
          "LengthChars": "0",
          "LengthParas": "0",
          "LengthLines": "0",
          "PlainContent": "",
          "FileSize": "0",
          "ColorSpace": "",
          "HighResFile": "",
          "Encoding": "",
          "Compression": "",
          "KeyFrameEveryFrames": "0",
          "Channels": "",
          "AspectRatio": "",
          "Orientation": null,
          "Dimensions": null
        },
        "WorkflowMetaData": {
          "Deadline": null,
          "Urgency": "",
          "Modifier": "WoodWing Software",
          "Modified": "2021-11-22T17:03:11",
          "Creator": "WoodWing Software",
          "Created": "2021-11-22T17:03:11",
          "Comment": "",
          "State": {
            "Id": "11",
            "Name": "Dossier - New",
            "Type": "Dossier",
            "Produce": null,
            "Color": "FF0000",
            "DefaultRouteTo": null,
            "Phase": "Selection"
          },
          "RouteTo": "",
          "LockedBy": "",
          "Version": "0.1",
          "DeadlineSoft": null,
          "Rating": "0",
          "Deletor": "",
          "Deleted": null
        },
        "ExtraMetaData": [
          {
            "Property": "C_CS_FILEFORMATVERSION",
            "Values": [
              ""
            ]
          },
          {
            "Property": "C_CS_STYLEID",
            "Values": [
              ""
            ]
          },
          {
            "Property": "C_CS_COMPONENTSET",
            "Values": [
              ""
            ]
          },
          {
            "Property": "C_CS_DE_COMPONENT_NAMES",
            "Values": [
              ""
            ]
          },
          {
            "Property": "C_CS_ARTICLE_TEMPLATE_ID",
            "Values": [
              ""
            ]
          },
          {
            "Property": "C_ELVIS_ARCHIVESTATUS",
            "Values": [
              ""
            ]
          },
          {
            "Property": "C_ELVIS_ARCHIVESTATUSMODIFIED",
            "Values": [
              ""
            ]
          }
        ]
      },
      "Targets": [
        {
          "PubChannel": {
            "Id": "1",
            "Name": "Print"
          },
          "Issue": {
            "Id": "1",
            "Name": "1st Issue",
            "OverrulePublication": null
          },
          "Editions": [
            {
              "Id": "1",
              "Name": "North"
            },
            {
              "Id": "2",
              "Name": "South"
            }
          ],
          "PublishedDate": null,
          "PublishedVersion": null
        }
      ]
    }
  },
  "comwoodwingstudioregistrationname": "JeffGapp-Webhook"
}