Webhooks

Version: 10.3

You can receive real-time notifications about events or workflow actions that occur in XM, 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 sends event details in an HTTP POST request to a specified endpoint. The webhook request payload can be sent as JSON or XML.

Note

To view or create webhooks, you must have a developer or admin role.

In XM, 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.

Note

XM 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.

Do you have some feedback for us?

If you have suggestions for improving this article,