Integrator > Integration Builder > Outbound integrations to the Integration Agent

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 event status changes, a notification is delivered, or a user responds to a message. The Integration Agent can consume the information contained in the webhook and take action based on the properties of the event.

Note the following 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 communication plan 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 webhooks. For general information about working with the Integration Agent, see the xMatters Integration Agent Guide.

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.

To configure an Integration Agent webhooks integration, see Outbound integrations. To use the POST trigger REST API to define callbacks for a single event, see Additional REST API methods.

Consuming webhooks in the Integration Agent

For more information about consuming webhooks in the integration agent, see the xMatters Integration Agent Guide. Additionally, you can contact your Client Success Manager for access to sample integrations that use webhooks.

Examples

The following sections show sample payloads for event status, device delivery, and notification response webhooks.