Creating your first integrator

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

An integrator is triggered by a request to 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 webhook: Go back to Transposit and add a webhook by going to the Settings gear icon > Webhooks section. Click the Add webhook 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. All incoming alerts will always appear in the Activity feed. It is optional to also set a Slack channel for the alert to appear in. (Note: The Slack channel must already exist; create it before adding the webhook.) Click Add.
  4. Trigger an alert in Slack: When your webhook is created, an endpoint URL is created. To trigger an alert 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 Activity feed or 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, 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"]
query_parameters = http_event.get("query_parameters", {})
parsed_body = http_event.get("parsed_body", {})

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

Metadata #

Also, in the sample application, you can see in integrator.response() operation's alertInformation dictionary there is an optional metadata property.

integrator.response(
{
"name": "alert_title",
"externalUrl": "alert_url",
"metadata": {
"app_name": app_name,
"parsed_body": parsed_body # Store any data that you want to use in the future from the wehbhook here, you can also use a different property name!
}
}, response_blocks)

This metadata property is a great place to store non-changing information that you want to access in an activity's later actions or runbooks. For example, you might reuse this data to query graphs or logs to get more data related to the alert or take action based on the incoming webhook. You might even store information related to the team the alert is associated with.

You will be able to access this metadata in any action run connected to the integrator's alert.

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:

# Get a query string parameter's value, replace query_param
query_param_val = query_parameters.get("query_param")

# Get a request body parameter's value, replace body_param
body_param_val = parsed_body.get("body_param")

# Optional: Run an operation to get more data, take action, etc.
try:
results = api.run("this.call_api", {
"param1": query_param_val,
"param2": body_param_val
})
except ValueError as ex:
error_blocks = api.run("block_kit_lib.markdown_text_section", {
"text": f"There was an issue performing an action:\n{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:

response_blocks = api.run(
"block_kit_lib.markdown_text_section", {
"text": f"Alert: Something happened with more info and data here!"
})

# Output an integrator response to Slack and activity timeline
integrator.response(
{
"name": "alert_title", # Set an alert title to the title of the incoming webhook content.
"externalUrl": "alert_url", # Set an alert_url to the url of the incoming webhook content.
"metadata": {
"app_name": app_name,
"parsed_body": parsed_body
}
}, response_blocks)

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