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.
recipient failures*** None of the targeted recipients could be immediately notified for an event. The type of failure, the first 100 targeted recipients, and the total number of targeted recipients

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

***To help speed accessibility and adoption of the new targeted recipient failures trigger for outbound integrations, it's being implemented in phases. Part of the event resolution process that the trigger uses to calculate available recipients relies on scheduled hosting service improvements, which means that you will experience different behavior based on your hosting region.

If you’re hosted in a region where service is already updated, the trigger fires whenever xMatters determines that there are no available recipients to notify at any time in the targeting and escalation process. If upgrades in your region aren't completed yet, the trigger fires only when xMatters determines that there are no available recipients to notify during the initial targeted notification. The following example further clarifies how this trigger works in different regions.

For more detailed information about the JSON payload for each webhook, refer to the Integration Builder scripting reference.

More about webhooks