Skip to content

update test #121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pijiang3 merged 2 commits into from
May 22, 2026
Merged

update test #121

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
160a7f1
update http-pull docs
pijiang3 May 22, 2026
2e66864
Merge branch 'main' of github.com:flashcatcloud/knowledge-base
pijiang3 May 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 141 additions & 93 deletions ...ll/8. Integrations/8.1 Alerts integration/8.1.60 Http Pull Alert Integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,85 @@
---
title: "HTTP Pull alert integration"
title: "HTTP Pull Alert Integration"
description: "Ingest alert events by periodically pulling from an external HTTP endpoint, ideal for systems that cannot push alerts."
date: "2025-05-22T10:00:00+08:00"
url: "https://docs.flashcat.cloud/en/flashduty/http-pull-integration-guide"
---

<Tip>**Plan requirement**: HTTP Pull integration requires a Pro or higher On-call plan.</Tip>
Ingest alert events by periodically pulling from an external HTTP endpoint, ideal for systems that cannot push alerts.

:::tips
HTTP Pull integration requires a Pro or higher On-call plan.
:::

<div class="hide">

## In Flashduty
---

You can obtain an integration push URL through either of these two methods:

### Using Private Integration

Choose this method when you don't need to route alert events to different channels - it's simpler.

<details>
<summary>Expand</summary>

1. Go to the Flashduty console, select **Channel**, and enter a specific channel's details page
2. Select the **Integrations** tab, click **Add Integration** to enter the integration page
3. Choose **HTTP Pull** integration, click **Save** to generate a card
4. Click the generated card to view the **Push URL**, copy it for later use

</details>

### Using Shared Integration

Choose this method when you need to route alerts to different channels based on alert event payload information.

<details>
<summary>Expand</summary>

1. Go to the Flashduty console, select **Integration Center => Alert Events** to enter the integration selection page
2. Select **HTTP Pull** integration:
- **Integration Name**: Define a name for this integration
3. Configure the default route and select the corresponding channel (after the integration is created, you can go to `Route` to configure more routing rules)
4. Click **Save** and copy the newly generated **push URL** for later use
5. Done

</details>
</div>

## Overview
---

<div class="md-block">

Flashduty supports two alert ingestion modes: **Push** and **Pull**. Most integrations use the push mode, where the external monitoring system actively sends alerts to Flashduty. However, some systems do not support webhook push, or alert data can only be retrieved through an API query.

HTTP Pull integration is designed for these scenarios — you simply provide an HTTP endpoint that returns alert data in JSON format, and Flashduty will periodically pull the data on a schedule you define, converting it into standard alert events for processing.

## Use cases
### Use Cases

- The monitoring system only provides a query API and does not support webhook push
- Alert data is stored in a database or object storage and must be queried via an HTTP endpoint
- A custom system cannot be retrofitted for push mode yet, and you want to integrate quickly via pull

## Configuration steps
### Configuration Steps

<Steps>
<Step title="Create the integration">
Go to the Flashduty console, navigate to **Integration Center → Alert Events**, search for and select the **HTTP Pull** integration.
</Step>
1. Go to the Flashduty console, navigate to **Integration Center → Alert Events**, search for and select the **HTTP Pull** integration
2. Configure request parameters (see [Request Parameters](#request-parameters))
3. Set the **pull cycle (cycle_seconds)** — how often data is pulled. Minimum is 30 seconds, default is 300 seconds (5 minutes)
4. Configure severity mapping if needed (see [Severity Mapping](#severity-mapping))
5. Configure pagination if your endpoint supports it (see [Pagination Configuration](#pagination-configuration))
6. Click **Save** to enable the integration. You can also manually trigger a pull from the integration details page

</div>

## I. Request Parameters <span id="request-parameters"></span>
---

<div class="md-block">

<Step title="Configure request parameters">
Configure the parameters Flashduty uses when making requests to your endpoint:

| Parameter | Required | Description |
Expand All @@ -34,30 +91,12 @@ Configure the parameters Flashduty uses when making requests to your endpoint:
| **Timeout** | No | Per-request timeout, 1–10 seconds. Defaults to 5 seconds |
| **RetryCount** | No | Number of retries on failure, 0–2. Defaults to 1 |

</Step>

<Step title="Configure the pull cycle">
Set the **pull cycle (cycle_seconds)** — how often data is pulled. Minimum is 30 seconds, default is 300 seconds (5 minutes).
</Step>

<Step title="Configure severity mapping (optional)">
If the severity values returned by your endpoint differ from Flashduty's standard, use **severity_mapping** to map them.

For example, if your system uses `high` / `medium` / `low`, you can map them to Flashduty's `Critical` / `Warning` / `Info`.
</Step>
</div>

<Step title="Configure pagination (optional)">
If your endpoint supports pagination, configure pagination parameters to retrieve complete data. See [Pagination configuration](#pagination-configuration) for details.
</Step>

<Step title="Save and enable">
After saving, the integration will automatically pull data on the configured schedule. You can also manually trigger a pull from the integration details page.
</Step>
</Steps>

## Response format requirements
## II. Response Format Requirements <span id="response-format"></span>
---

<a id="response-format"></a>
<div class="md-block">

Your HTTP endpoint must meet the following requirements:

Expand Down Expand Up @@ -89,23 +128,24 @@ Each element in `items` corresponds to one alert event. The fields are consisten
}
```

### Event field reference
### Event Field Reference

| Field | Required | Type | Description |
| :--- | :--- | :--- | :--- |
| event_status | Yes | string | Alert status. Enum (capitalized): `Critical`, `Warning`, `Info`, `Ok` (recovery) |
| title_rule | Yes | string | Alert title, up to 512 characters |
| alert_key | No | string | Alert identifier for updating or recovering existing alerts. Up to 255 characters; auto-generated if not specified |
| description | No | string | Alert description, up to 2048 characters |
| labels | No | map | Alert label collection in key-value format. Up to 50 labels |
Field|Required|Type|Description
:-:|:-:|:-:|:---
event_status | Yes | string | Alert status. Enum (capitalized): `Critical`, `Warning`, `Info`, `Ok` (recovery)
title_rule | Yes | string | Alert title, up to 512 characters
alert_key | No | string | Alert identifier for updating or recovering existing alerts. Up to 255 characters; auto-generated if not specified
description | No | string | Alert description, up to 2048 characters
labels | No | map | Alert label collection in key-value format. Up to 50 labels

<Warning>
A maximum of 100 events are processed per page, and up to 2000 events in total across all pages per pull. Excess events are truncated and recorded in the pull history.
</Warning>
> A maximum of 100 events are processed per page, and up to 2000 events in total across all pages per pull. Excess events are truncated and recorded in the pull history.

## Template variables
</div>

<a id="template-variables"></a>
## III. Template Variables <span id="template-variables"></span>
---

<div class="md-block">

URL and Body support Go `text/template` syntax. The following variables are available to dynamically generate request content:

Expand Down Expand Up @@ -134,9 +174,12 @@ Using ISO-formatted time in the Body:
}
```

## Pagination configuration
</div>

## IV. Pagination Configuration <span id="pagination-configuration"></span>
---

<a id="pagination-configuration"></a>
<div class="md-block">

If your endpoint cannot return all data in a single response, you can configure cursor-based pagination.

Expand All @@ -148,27 +191,14 @@ If your endpoint cannot return all data in a single response, you can configure
| **param_name** | Pagination parameter name, e.g., `cursor` or `page_token` |
| **inject_to** | Where to inject the pagination parameter: `query` (append to URL query string) or `body` (merge into request body JSON) |

### Pagination workflow
### Pagination Workflow

<Steps>
<Step title="Initial request">
Flashduty sends the first request without pagination parameters.
</Step>
1. Flashduty sends the first request without pagination parameters
2. The next-page cursor value is extracted from the response JSON using `next_value_path`
3. The cursor value is injected into the next request using `param_name` as the key, either in the query string or the body
4. Pagination stops when `next_value_path` returns no value, the response contains an empty array, or the `max_pages` limit is reached

<Step title="Extract cursor">
The next-page cursor value is extracted from the response JSON using `next_value_path`.
</Step>

<Step title="Subsequent requests">
The cursor value is injected into the next request using `param_name` as the key, either in the query string or the body.
</Step>

<Step title="Termination conditions">
Pagination stops when `next_value_path` returns no value, the response contains an empty array, or the `max_pages` limit is reached.
</Step>
</Steps>

### Pagination response example
### Pagination Response Example

```json
{
Expand All @@ -183,35 +213,13 @@ Pagination stops when `next_value_path` returns no value, the response contains

With `next_value_path` set to `pagination.next_cursor`, the system will automatically use `eyJpZCI6MTAwfQ==` as the parameter value for the next page request.

## FAQ

<AccordionGroup>
<Accordion title="Pull failed with a URL access denied error?">
For security reasons, Flashduty (non-private deployment) does not allow access to private network addresses (e.g., `127.0.0.1`, `10.x.x.x`, `192.168.x.x`). Ensure your endpoint is accessible from the public internet.

This restriction does not apply to private deployment versions.
</Accordion>

<Accordion title="How do I view pull history and error details?">
In the integration details page under **Pull History**, you can view the results of each pull execution, including status, number of events pulled, error messages, and more.
</Accordion>

<Accordion title="Pull succeeds but no new alerts are generated?">
Check the following:
</div>

1. Confirm the JSON response contains an `items` array and it is not empty.
2. Confirm each event has `event_status` and `title_rule` fields.
3. If you use `alert_key`, check whether the alert is a duplicate — events with identical status and content are deduplicated and discarded.
4. Check if any drop rules, inhibit rules, or silence rules are matching.

For more information, see [Noise reduction](/en/on-call/channel/noise-reduction).
</Accordion>
## V. Severity Mapping <span id="severity-mapping"></span>
---

<Accordion title="Can I manually trigger a pull?">
Yes. Click the manual trigger button on the integration details page. Manual triggers have a 60-second cooldown and cannot run concurrently with an ongoing scheduled pull.
</Accordion>
<div class="md-block">

<Accordion title="How does severity mapping work?">
If your system uses custom severity identifiers (e.g., `P1`, `high`), you can configure mapping rules in the integration settings. For example:

| Your value | Flashduty value |
Expand All @@ -221,5 +229,45 @@ If your system uses custom severity identifiers (e.g., `P1`, `high`), you can co
| P3 | Info |

Values that do not match any mapping are processed as-is.
</Accordion>
</AccordionGroup>

</div>

## VI. FAQ
---

<details>
<summary>Pull failed with a URL access denied error?</summary>

For security reasons, Flashduty (non-private deployment) does not allow access to private network addresses (e.g., `127.0.0.1`, `10.x.x.x`, `192.168.x.x`). Ensure your endpoint is accessible from the public internet.

This restriction does not apply to private deployment versions.

</details>

<details>
<summary>How do I view pull history and error details?</summary>

In the integration details page under **Pull History**, you can view the results of each pull execution, including status, number of events pulled, error messages, and more.

</details>

<details>
<summary>Pull succeeds but no new alerts are generated?</summary>

Check the following:

1. Confirm the JSON response contains an `items` array and it is not empty.
2. Confirm each event has `event_status` and `title_rule` fields.
3. If you use `alert_key`, check whether the alert is a duplicate — events with identical status and content are deduplicated and discarded.
4. Check if any drop rules, inhibit rules, or silence rules are matching.

For more information, see [Noise reduction](/en/on-call/channel/noise-reduction).

</details>

<details>
<summary>Can I manually trigger a pull?</summary>

Yes. Click the manual trigger button on the integration details page. Manual triggers have a 60-second cooldown and cannot run concurrently with an ongoing scheduled pull.

</details>
Loading
Loading