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.
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, or Tracking Report.||The user that made the comment and the content of their comment.|
|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 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
- For more information about including form properties in outbound integrations, see Property settings.
- For more information about including integrated properties in outbound integrations, see Integrated properties.
- For information about using webhooks (callbacks) with the REST API, see Additional REST API methods.
- For more information about working with the Integration Agent, see Outbound integrations to the Integration Agent.