> For the complete documentation index, see [llms.txt](https://docs.alertifii.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alertifii.com/integrations.md).

# 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](#email-endpoint) or [HTTP request](#webhook-endpoint) to your integration endpoint.
2. Alertifii creates an alert using the [templates](#templates) to transform the incoming data.
3. The newly created alert is sent to the [destination](#destination).
4. The destination determines which user(s) are notified.

<figure><img src="/files/JjPuSbe8IfaD860YswNn" alt=""><figcaption><p>Alertifii Integration -> Alert Transformation Process</p></figcaption></figure>

## Endpoints

Each integration has two endpoints:

* [Email Endpoint](#email-endpoint) - A unique email address that can receive emails.
* [Webhook Endpoint](#webhook-endpoint) - A unique endpoint that can receive HTTP GET or POST requests.

<figure><img src="/files/DMDxZVZvTcUbqNhF3g5o" alt=""><figcaption><p>Integration Endpoints</p></figcaption></figure>

{% hint style="danger" %}
Keep your integration endpoints secret. Anyone with knowledge of the endpoint address can publish to it, possibly creating unwanted alerts in your account.
{% endhint %}

### Email Endpoint

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

<figure><img src="/files/GiWvYPUgwCtBD0plbZK6" alt=""><figcaption><p>Send an email to the integration endpoint</p></figcaption></figure>

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.

<figure><img src="/files/Can0f6lzycDeoXN5mMF8" alt=""><figcaption><p>Example of making a GET request (in a web browser) to the webhook endpoint.</p></figcaption></figure>

<figure><img src="/files/fxApGBmunRvrq7ADf6Oh" alt=""><figcaption><p>Example making a POST request (in a tool called Postman) to the webhook endpoint.</p></figcaption></figure>

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](#templates) 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:

```json
{
    "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](http://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.

<figure><img src="/files/rGAStdoBsDWt2SmNhice" alt=""><figcaption><p>Integration Destination</p></figcaption></figure>

## 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.&#x20;

   <figure><img src="/files/qIGfZKk1yGoek8NtVWeu" alt=""><figcaption><p>Maintenance mode button.</p></figcaption></figure>
2. Select the duration of how long you would like this maintenance window to last.&#x20;

   <figure><img src="/files/lFIyKyqSy2P2gswvuzzX" alt=""><figcaption><p>Maintenance mode duration options.</p></figcaption></figure>
3. If you are sure, click confirm on the confirm dialog.&#x20;

   <figure><img src="/files/EWUHOXhNaAUl4w8kLgvp" alt=""><figcaption><p>Enable maintenance mode confirm dialog.</p></figcaption></figure>

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

<figure><img src="/files/R09H7ZDLl7jPOTFFIRNF" alt=""><figcaption><p>Maintenance mode indicator</p></figcaption></figure>

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.&#x20;

   <figure><img src="/files/N8o5UNAUOKRub5AL3tgz" alt=""><figcaption><p>Click 'x' on maintenance mode indicator.</p></figcaption></figure>
2. If you are sure, click the confirm on the dialog.&#x20;

   <figure><img src="/files/R768IAQGMrQz7xajdAl5" alt=""><figcaption><p>Disable maintenance mode confirm dialog.</p></figcaption></figure>

## Aggregation

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

1. Aggregate By Template - A [template](#templates) 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:

```ruby
# 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](https://pushover.net/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.