The Getting Integrated Guide (part 1)

Follow me for updates!

Have you ever asked a question that started with "Can xMatters Integrate with..." and then looked over our existing integrations here without seeing your specific answer?


Well, look no further than the "Getting Integrated Guide" (GIG). This will be a multi-part series for how to build an integration to xMatters.

  1. This one!
  2. How to Build a Communication Plan (GIG part 2)
  3. [Deprecated] Authentication and Permissions (GIG part 4)
  4. First Look at Webhooks (GIG part 5)
  5. Integration with the IA and Communication Plans (GIG part 6)
  6. Inbound REST through the integration agent (GIG part 8)
  7. Generic Device with xMod (GIG part 9)
  8. Integrated Properties! Pull data from an external system! (GIG Part 10)
  9. Aaaaaargh! I broke it! Troubleshooting (GIG part 11)
  10. Cloud Integrations Part 1 (GIG part 12)
  11. [Deprecated] Making HTTP calls from the IA (GIG part 13)
  12. Integration Builder Beta Access (GIG Part 14)
  13. Custom HTTP responses from the IA (GIG 15)
  14. Behold the Integration Builder!! (Cloud Integrations Part 2)
  15. GIG: reporting errors in processing events
  16. GIG: Working with XML and SOAP in the Integration Builder
  17. GIG: Generating Basic Auth Headers
  18. GIG: Follow up notification based on response with bonus QR codes!
  19. GIG: Building tables for fun and format
  20. GIG: What HTML tags are allowed in properties?
  21. GIG: Would you like your xM On Call info displayed HipChat or Slack?
  22. GIG: xMatters and AWS
  23. GIG: Shared Libraries are here!
  24. GIG: Google Stackdriver: Alerting for virtually stacked drives
  25. GIG: Embedding custom URIs
  26. GIG: Special Agent 6
  27. GIG: Adding custom fields to the Splunk Alert Actions Integration
  28. GIG: Converting an integration from using REAPI to XMAPI

In this premier installment, we'll define a few terms and go over all of the (currently) available methods for "integrations". In subsequent releases, we'll dive into each item in more detail and provide working examples. 


We'll also dig into all the cool new technology toys the engineers have been cooking up and are just about ready to serve. So be sure to follow this page as I'll update it with links and technologies as we go. 



What is an "integration"? The term "integration" gets thrown around a lot and it means different things to different people. For this series, we'll talk about event integrations that are either "one way", "closed loop" or "webhook only".

  • One way integrations refer to integrations where the event starts in an external system, sends the payload to xMatters (either through the IA or directly to the REST API) and notifies the recipient. Recipients may or may not respond and their response is logged in xMatters, but that is where it stops. So there is no payload back to the management system. Period.
  • Compare this with closed loop integrations that follow the same path as the One Way integrations, but have an additional step of updating the management system either with delivery updates, event status updates or recipient responses.
  • Again, compare these with webhook-only integrations where the event originates in xMatters (probably through a Message panel), then through a webhook update an external system. 


Additionally, there are data integrations that are used to synchronize data such as groups, shifts, users and/or devices from an external system to xMatters. 


Finally, we'll talk about directions: inbound means getting stuff into xMatters, while outbound means getting stuff out of xMatters. 


Getting events into xMatters (inbound)

There are a variety of ways to get events from an external system or application into xMatters. Note that the integration agent acts as middleware in front of the REST API. 

Communication Method Integration Agent REST API Integration Builder
Command Line Yes No No
Email No* Yes No


*While it would be possible to write an integration service to poll an email inbox, that is out of scope for this document.... for now...


Getting responses back from xMatters (outbound)

The integration agent polls xMatters for responses and can then take action on an external system. Using webhooks from the REST API, you can make REST Web Service calls to external systems. 

Communication Method Integration Agent Webhooks (JSON) Integration Builder
Command Line Yes No No


 Click here for the next installment!

Have more questions? Submit a request


  • 0
    Cameron Stewart

    Loving this series - thanks for posting!

Please sign in to leave a comment.
Powered by Zendesk