# Alert sources

Send alerts from Sentry, Grafana, Datadog, CloudWatch or any script to Pulsefast, and get grouped incidents with a timeline.


*Alert sources are in early access.*

An alert source is a secret URL that turns alerts from your other tools into Pulsefast incidents. Your team is paged through the channels you pick, repeats are grouped into one incident, and every incident gets a timeline.

## Create one

Under **Incidents → Alert sources**, add a source, name it after the tool ("Sentry", "Grafana") and pick the channels to page. You get a URL like `https://pulsefast.io/in/in_…`, shown once. Anyone with it can send alerts, so keep it secret; **New URL** replaces it if it leaks.

## Send alerts

`POST` JSON to the URL:

```sh
curl -X POST https://pulsefast.io/in/in_YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Checkout errors spiking", "key": "checkout-5xx", "severity": "critical"}'
```

| Field | Notes |
|---|---|
| `title` | What's wrong. Shown in pages and on the incident. |
| `key` | Groups alerts: the same key while an incident is open adds to it. Defaults to the title. |
| `status` | `firing` (default) or `resolved`. |
| `severity` | `critical` (default), `warning` or `info`. |
| `details` | Anything: text or JSON. Kept on the incident as the raw alert. |
| `links` | `[{"title": "Dashboard", "url": "https://…"}]` |

Send an array to report several alerts at once (up to 100). The response lists what happened to each: `opened`, `added` (grouped into an open incident), `reopened`, `resolved`, or `ignored` (a resolve for nothing open).

## Grouping and flapping

Alerts with the same `key` from the same source belong to one incident while it's open. If an incident resolves and the same key fires again within 10 minutes, the incident **reopens** instead of a new one starting, so a flapping service doesn't page you over and over with new incidents. The same applies to Pulsefast's own monitors.

Your team is paged when an incident opens or reopens, and told when it resolves. Repeat alerts for an open incident are recorded on its timeline without paging again.

## Tools with their own format

Pick the tool when you create the source; the setup steps are shown with the URL.

| Tool | How it connects | Grouping and resolving |
|---|---|---|
| Prometheus Alertmanager | A `webhook_configs` receiver with `send_resolved: true`. | By alert fingerprint; resolved alerts resolve the incident. Severity from the `severity` label. |
| Grafana | A Webhook contact point. | Same as Alertmanager (Grafana uses its format). |
| Sentry | An internal integration with Alert Rule Action on, subscribed to issue events, added to your alert rules. Paste its client secret to check signatures. | Issue alerts group by issue; resolving or ignoring the issue in Sentry resolves the incident. Metric alerts group by alert and resolve when Sentry says so. |
| Datadog | A Webhooks integration with the payload shown during setup; mention it in your monitors. | By alert ID; recovery resolves. |
| AWS CloudWatch | An SNS topic with an HTTPS subscription to the URL (Pulsefast confirms it automatically) as the alarm action for ALARM and OK. Messages must carry a valid SNS signature, so only Amazon can send them. | By alarm; OK resolves, INSUFFICIENT_DATA is ignored. |

## Limits

600 alerts a minute per source, and up to 256 KB per request.