Outbound integrations to the Integration Agent

You can configure on outbound integration to send webhooks to an Integration Agent when certain system actions occur, such as when an alert status changes, a notification is delivered, a user responds to a message, or a user comments on an alert. The Integration Agent can consume the information contained in the webhook and take action based on the properties of the alert.

There are some important technical considerations about building outbound integrations for use with the Integration Agent:

  • The Integration Agent must be running in indirect mode. When an Integration Agent runs in indirect mode, it periodically polls xMatters for updates. This enables the integration to work with xMatters across a company firewall.
  • All integrations to forms are made through the applications event domain.
  • When a webhook occurs, the Integration Agent calls the apia_callback function.

This topic describes how to work with webhooks to the Integration Agent. For general information about working with webhooks, including the available types of webhooks and when to use them, see Outbound integration triggers. For general information about working with the Integration Agent, see the Integration Agent overview.

The integration service and agent identifier

To configure an outbound integration for the Integration Agent, you must provide the name of the integration service. You may optionally include the agent identifier.

To help you determine whether you should include the agent identifier, consider how outbound integrations work when there are no integration agents available to consume the webhook. Webhooks are sent to the first integration service that can consume them.

  • If there are no integration services available and an agent identifier is not supplied, the webhook is discarded.
  • If an agent identifier is supplied, the webhook is queued until the specific Integration Agent is available.

Provide an agent identifier when you want xMatters to queue webhooks in the situation that no integration agents are available (such as when the integration service is down for maintenance). You may not need to provide an agent identifier if you have several redundant integration services that provide uninterrupted service when one is offline.

  1. In the Workflows menu, click Agents.
  2. In the Integration Agents section, locate the Integration Agent that will consume the callback.
  3. Click Details to see more information about the Integration Agent; the ID is the agent identifier.

To configure an Integration Agent webhooks integration, see Outbound integration triggers. To use the POST trigger REST API to define callbacks for a single alert, see the xMatters REST API.

Consuming webhooks in the Integration Agent

For more information about consuming webhooks in the integration agent, see the Integration Agent overview. Additionally, you can find sample integrations that use webhooks on the xMatters Support site.

Examples

The following sections show sample payloads for alert status, device delivery, notification response, and annotation (alert comment) webhooks.

{
  "date":"18-01-25 00:11:43.505",
  "apia_priority":"normal",
  "incident_id":"INCIDENT_ID-39404000",
  "agent_application_id":"tir-na-noc/10.2.0.111:8081",
  "additionalTokens":{
  },
  "apia_process_group":"apia_default_group",
  "agent_client_id":"applications|sample-relevance-engine",
  "apia_source":"xmatters: ",
  "xmatters_callback_type":"status",
  "username":"networkops",
  "status":"active",
  "eventidentifier":"39404000"
}
{
  "date":"18-01-25 00:11:46.979",
  "message":"Notification delivered",
  "deviceid":"202062",
  "apia_priority":"normal",
  "agent_application_id":"tir-na-noc/10.2.0.111:8081",
  "incident_id":"INCIDENT_ID-39404000",
  "deliverystatus":"Delivered",
  "recipient":"boberon",
  "eventtype":"LIVE_NOTIFICATION_PROVIDER_DELIVERED",
  "additionalTokens":{
  },
  "apia_process_group":"apia_default_group",
  "agent_client_id":"applications|sample-relevance-engine",
  "device":"Work Email",
  "apia_source":"xmatters: ",
  "xmatters_callback_type":"deliveryStatus",
  "eventidentifier":"39404000"
}
{
  "annotation":"null",
  "date":"18-01-25 00:12:22.349",
  "apia_priority":"normal",
  "incident_id":"INCIDENT_ID-39404000",
  "agent_application_id":"tir-na-noc/10.2.0.111:8081",
  "response":"Acknowledge",
  "recipient":"boberon",
  "additionalTokens":{
  },
  "apia_process_group":"apia_default_group",
  "agent_client_id":"applications|sample-relevance-engine",
  "device":"Work Email",
  "apia_source":"xmatters: ",
  "eventidentifier":"39404000",
  "xmatters_callback_type":"response"
}
{
  "date":"18-01-25 00:12:32.195",
  "author":{
  "id":"54716eee-6e9a-40b4-b90f-ed7410785826",
  "targetName":"boberon",
  "recipientType":"Person",
  "firstName":"Bill",
  "lastName":"Oberon"
  },
  "eventproperties":"null",
  "apia_priority":"normal",
  "incident_id":"INCIDENT_ID-39404000",
  "agent_application_id":"tir-na-noc/10.2.0.111:8081",
  "comment":"I'm in the area and will arrive shortly.",
  "apia_process_group":"apia_default_group",
  "event":{
  "id":"cf4ba93b-8e16-4524-acd3-3ccab543ee1b",
  "eventId":39404000
},
"agent_client_id":"applications|sample-relevance-engine",
"apia_source":"xmatters: ",
"eventidentifier":"39404000",
"xmatters_callback_type":"annotation"
}