# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alertifii.com/integrations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.