Creating your first integrator

An integrator is defined by one Transposit Dev Platform application and relay alerts and related data from external services. In some cases, users may want to create an incident based on these alerts or take other action.

An integrator is triggered by a request from a webhook URL that Transposit provides.

This tutorial will guide you to make your first integrator in Python.

Creating your first integrator #

  1. Fork sample application: Go to this sample application and fork this app at the top of the page. Make sure to change the owner to the name of your organization, not your personal account.
  2. Deploy integrator: In your application in the Transposit Dev Platform, go to Deploy > Mission Control, change the type to “Integrator,” and save. You should use the latest tag for ease of development.
  3. Create a trigger: Go back to Transposit and add a trigger by going to the Setting > Triggers section. Click the Add Trigger button and select a Custom integrator. Your integrator’s identifier is in the format of maintainer/service_name:tag. If you are following this tutorial, your integrator identifier will be your_organization_name/application_name:latest. Then, you will enter a Slack channel name you want to test it on. (Note: The Slack channel must already exist; create it before adding the trigger.)
  4. Trigger an alert in Slack: When your trigger is created, an endpoint URL is created. To trigger an alert in Slack from your integrator, curl [endpoint_url] on command line or go to the URL in your browser. This acts like an external service triggering your integrator. You should now see an alert in the specified Slack channel.

Where to go from here? #

Now that you have set up your first custom integrator, you can use the endpoint URL with any external service that supports webhooks to trigger alerts in Transposit. If you trigger the webhook URL from another external service in the sample application, you will see a Slack message with the http_event body. The structure of the data being sent to Transposit with the endpoint URL often depends on the service.

Incoming data #

In the sample application, you can see we store different properties such as headers, query_parameters, and parsed_body to retrieve data from the external service to use with Transposit.

http_event = params["context"]["parameters"]["http_event"]
headers = http_event["headers"]
query_parameters = http_event["query_parameters"]
parsed_body = http_event.get("parsed_body", {})

In the http_event you can see where the data you want to use is stored. Not all external services will contain each of these properties.

Running an operation #

In some cases, you might want more data or take action based on an integrator being triggered. For example, you can call external services for more data as seen in the sample application in the try/except that is commented out:

results ="this.call_api", {
"param1": query_param_val,
"param2": body_param_val
except ValueError as ex:
error_blocks ="block_kit_lib.markdown_text_section", {
"text": f"There was an issue performing an action: {str(ex)}"
integrator.response({"name": "Template integrator alert"}, error_blocks)
return {}

Sending alert messages #

As seen in the sample application, we use the block_kit_lib connector to make it easier to form Slack Block Kit UI followed by integrator.response(alertInformation, blocks). Most of the time, this would look like something like this:

output_blocks ="block_kit_lib.markdown_text_section", {
"text": text
integrator.response({"name": "Template integrator alert"}, output_blocks)

Your text value will be what you want to display to a user, as well as your activity timeline.