Integrations

Integrations are responsible for taking incoming emails or webhook requests and transforming them into alerts. The process is as follows:

1. A third-party system sends Alertifii an email or HTTP request to your integration endpoint.

2. Alertifii creates an alert using the templates to transform the incoming data.

3. The newly created alert is sent to the destination.

4. The destination determines which user(s) are notified.

Alertifii Integration -> Alert Transformation Process

Endpoints

Each integration has two endpoints:

• Email Endpoint - A unique email address that can receive emails.

• Webhook Endpoint - A unique endpoint that can receive HTTP GET or POST requests.

Integration Endpoints

Keep your integration endpoints secret. Anyone with knowledge of the endpoint address can publish to it, possibly creating unwanted alerts in your account.

Email Endpoint

To create an alert using the email endpoint, simply send an email to the integration's email endpoint.

Send an email to the integration endpoint

The templates should use the following (default):

• Title Template - <%= request['params']['subject'] %>

• Body Template - <%= request['params']['body'] %>

Webhook Endpoint

To create an alert using the webhook endpoint, simply make a GET or POST request to the integration's webhook endpoint.

Example of making a GET request (in a web browser) to the webhook endpoint.

Example making a POST request (in a tool called Postman) to the webhook endpoint.

By default, the webhook endpoint uses the subject and body parameters sent to it as the title and body of the alerts respectively. However, this can be changed using template to match any body you send to the webhook.

Templates

Templates are a way to extract information from incoming request. Templates can use the data sent by your webhook or email to be used for alert fields.

Template Example

The following JSON was sent by your 3rd party system to the Alertifii integration endpoint:

{
    "custom_field_1": "error",
    "custom_field_2": "example-id-123",
    "custom_field_3": "5xx Error",
    "custom_field_4": "500 error observed 10x on www.example.com"
}

Using the following templates:

• Title Template - <%= request['params']['custom_field_3'] %>

• Body Template - <%= request['params']['custom_field_1'] %> - <%= request['params']['custom_field_4'] %>

The output would be the following:

• Alert Title - "5xx Error"

• Alert Description - "error - 500 error observed 10x on www.example.com"

Destination

Each integration has one destination. The destination determines which user(s) will be notified of the alert.

• If the destination is a team, Alertifii sends notifications to all users that are on-call for the team.

• If the destination is a user, Alertifii will notify the single user.

Integration Destination

Maintenance Mode

Each integration can be put into "maintenance mode". During maintenance mode, integration will no longer create alerts. This is especially helpful if you have a system that gets noisy during known maintenance.

Enable Maintenance Mode

1. Click the moon button next to the integration that should enter maintenance mode.

   

   Maintenance mode button.
2. Select the duration of how long you would like this maintenance window to last.

   

   Maintenance mode duration options.
3. If you are sure, click confirm on the confirm dialog.

   

   Enable maintenance mode confirm dialog.

The integration will now appear with a purple moon icon, indicating the integration is in maintenance mode.

Maintenance mode indicator

After the selected duration, the maintenance window will automatically be disabled.

Disable Maintenance Mode

To disable maintenance mode (before the configured duration)

1. Click the 'x' next to the purple moon icon.

   

   Click 'x' on maintenance mode indicator.
2. If you are sure, click the confirm on the dialog.

   

   Disable maintenance mode confirm dialog.

Aggregation

Alertifii supports simple aggregation. Two fields determine how Alertifii will aggregate alerts:

1. Aggregate By Template - A template that creates a aggregation key (aka "fingerprint"). Aggregation keys apply across all integrations.

2. Aggregate For (Minutes) - The duration in minutes to aggregate alerts with this same key.

Below is the pseudo code that shows how we aggregate alerts:

# fingerprint and dedup
if aggregate_by.present? && aggregate_for.present?
  fingerprint = safely(default: nil) { ERB.new(aggregate_by).result_with_hash(hash) }&.strip

  # only do fingerprinting if we were able to generate a non-blank fingerprint
  if !fingerprint.blank?
    dup_alert = account.alerts.where(fingerprint: fingerprint).where("created_at > ?", Time.current - aggregate_for.to_i.minutes).first

    # if we have a dup, update the existing alert
    # otherwise fingerprint the alert
    if dup_alert
      dup_alert.increment!(:dedup_count)
      alert = nil
    else
      alert.fingerprint = fingerprint
    end
  end
end

Pushover API Adapter

Alertifii supports a Pushover API adapter so you can simply switch the domain of your existing scripts.

1. Switch the domain from api.pushover.net -> api.alertifii.com

2. Change the Pushover token and user to be your integration id (ex: int_abcdefghijklmn)

POST an HTTPS request to https://api.alertifii.com/1/messages.json with the following parameters:

• token - (required) - your integration's ID

• message - (required) - Text to be used as the body of the alert, aswell as the title if no title parameter is passed in.

• title - (optional) Text to be used as the title of the alert. Defaults to message parameter.

• user - (optional) - The team or user id to route the alert to. Defaults to integration destination.

• priority - (optional) - A value between -2 and 2. Defaults to integration priority.

• sound - (optional) - The name of a supported sound. Defaults to integration sound.