Webhooks
You can receive real-time notifications about events or workflow actions that occur in XM Cloud, by adding a webhook. You can also use a webhook to run external validation on item workflow state changes.
You can create a webhook that tracks a system event or workflow action. When a tracked event occurs or a workflow action runs, XM Cloud sends event details in an HTTP POST request to a specified endpoint. The webhook request payload can be sent as JSON or XML.
To view or create webhooks, you must have a developer or admin role.
In XM Cloud, there are three types of webhooks:
-
Webhook event handler
-
Webhook submit action
-
Webhook validation action
Webhook event handler
You can receive information about supported system events by creating a webhook event handler.
For example, you can configure a webhook event handler to send a request to a specified endpoint when an item with the webpage template is created.
Webhook submit action
You can receive information when an item changes workflow state or when a workflow command runs by adding a webhook submit action.
For example, you can insert a webhook submit action in the approved state of a workflow. Then when an item using the workflow moves to the approved state, the webhook sends an HTTP request to a specified endpoint.
Webhook validation action
You can provide a third-party service the ability to approve or reject changes in the workflow state of an item, by adding a webhook validation action. When a webhook validation action sends a request, the third-party service must return a response.
For example, you can add a webhook validation action to a command item of a workflow that changes the state from in review to approved. When the command is executed, the webhook sends an HTTP request to the specified endpoint.
The endpoint must then return a response validating the command. If the endpoint does not validate the command, the item will not change its state.
Authorization item
If the destination endpoint requires authentication, you must create an authorization item and assign it to the webhook.
Error handling
If you receive an error when sending a request, check the log file for error information.
XM Cloud does not support resending a request when an error occurs at the destination endpoint.
Timeouts
The default maximum time to send all webhooks in a particular request is 10 seconds.
Testing a webhook
If you haven’t set up an endpoint, you can use a webhook testing website to create an endpoint to test your webhook.