Skip to main content
The xMatters integration provides group search, on-call lookup, alert inspection, response lookup, paging, comments, and alert lifecycle actions.

​
Connect xMatters

  1. Choose an xMatters integration user with access to the groups and alerts you want Serval to use. The connection inherits this user’s permissions.
  2. Open the user’s profile, then select More Actions → Manage API Keys → Create API Key Credential. Create a credential and save its API key and one-time secret. See xMatters API key administration.
  3. In Serval’s app catalog, select xMatters and connect an instance.
  4. Enter an instance name, your tenant hostname (for example, company.xmatters.com), the API key, and its secret. The x-api-key- prefix is optional. Use the hostname only; do not paste a trigger URL here.
  5. Run the connection health checks. They read groups, alerts, and one visible on-call group’s schedule without sending notifications. If no on-call group is visible, the schedule check reports that it was not exercised.
The API key and secret are stored as integration credentials. You can rotate them in the connection form. To change the tenant hostname, create a new connection. Revoking the key or deleting its xMatters user prevents the connection from working.

​
Configure paging

An xMatters administrator must set up the Trigger Alerts by Webhook template and enable its flow. Select API Key Authentication for the HTTP trigger. The trigger’s Basic Authentication option is for a user password and does not accept these API-key credentials. Copy the trigger UUID from the URL path:
Use that UUID as the Trigger ID input to Page an xMatters Group. Find the recipient using Find xMatters Groups, then supply its explicit group UUID, summary, and message. Serval supplies the resolved group name in both the recipients query parameter and the template payload, replacing the default recipient from the copied URL. Group names containing commas are not supported by this workflow; choose an unambiguous group name in xMatters. The workflow maps its message to the template’s description field and sends MEDIUM priority. Custom flows may need a custom Serval workflow. The xMatters flow controls escalation and delivery.

​
Install workflows

The Alerting and On-Call bundle includes:

​
Interpret results

A paging result marked accepted means xMatters accepted the flow request. It does not confirm alert creation or delivery. Use Search xMatters Alerts with the returned requestId to find resulting alerts. The search can initially be empty or return more than one alert. Inspect response entries separately. List workflows return one bounded page with hasMore and nextOffset. Pass the next offset to continue. On-call results also indicate whether nested member lists are incomplete. An empty result only describes data visible to the API user. Lifecycle actions accept ACTIVE (resume), SUSPENDED (pause), and TERMINATED (stop permanently). Termination cannot be undone. None is an acknowledgment. The API calls alerts events, and workflows use their UUIDs rather than their numeric display IDs.

​
Troubleshooting

  • 401 or 403: check the key, secret, user’s status and permissions, and the trigger’s authentication setting. REST access and flow-trigger access are separate checks.
  • 429 or server errors during reads: Serval makes up to three attempts using bounded backoff. If the read still fails, try again later.
  • Paging timeout or interruption: a page might already have been sent. Inspect the xMatters Activity log before retrying. Paging has no exactly-once guarantee.
  • No alert found for a request ID: allow time for the flow to execute and check its Activity log. Do not resubmit a page solely because this search is empty.
This integration does not automatically create xMatters flows, edit schedules, provision users, or synchronize Serval tickets through callbacks.