Outbound integration webhooks

Outbound integrations can be configured for use with any web application that can consume POST requests over HTTP or integrations that use the xMatters Integration Agent in indirect mode.

Webhooks can also be especially powerful when used in conjunction with the xMatters REST API. For more information about using webhooks with the REST API, see Additional REST API methods.

Information included in webhooks

Webhooks include information about the action that occurred, the associated event, and the value of some form properties. By using form properties in a webhook, you can communicate any information that is available to the form when the event is initiated. You may want to create form properties that are used exclusively for communicating to third-party systems using webhooks. For example, you could create a form property that prompts the user to select a category that exists in a third-party system. This field can be passed to the webhook but does not need to be included in the message body of notifications that are sent to recipients.

Every webhook includes some common information:

  • event identifier: a unique identifier that can be used to track the event that generated the webhook
  • date: the date and time the webhook is made
  • event properties: values of form properties that have been flagged to be included in webhook

In addition to this common information, each type of webhook payload includes information about the action that triggered it.

Type System event Included information
event status An event is started, suspended, resumed, or terminated. The status of the event and the user who initiated the event status change.
event comment* A user adds a comment from the mobile app, xMatters Inbox, email, Tracking Report.

The user that made the comment and the content of their comment.

escalations An escalation occurs in a group. The group containing the shift with the escalation, the reason for the escalation, the user that escalated the event (if applicable), the type of escalation, the recipients the event escalated from, and the recipients the event escalated to.
message delivery A notification is delivered to a device, or notification delivery fails. The user and device that the message is being delivered to and whether the delivery was successful.
response A user responds to a message. The user and device that made the response, their response choice, and annotations from the mobile app included with the response**.

*The Event Comments trigger won't (yet) be triggered by comments added using the POST /event/{eventId}/annotations endpoint in the xMatters REST API.

**The introduction of event comment webhooks in the Knight quarterly release of xMatters On-Demand allows us to begin deprecating the inclusion of mobile app annotations in response webhooks. We will continue to support the current functionality of response webhooks, including mobile app annotations, for two additional quarterly release cycles.

For more detailed information about the JSON payload for status, delivery, and response webhooks, refer to the Integration Builder scripting reference.

More about webhooks