# Alert adapter integration

> Normalize monitoring-provider events and submit them through Firewatch's alert ingestion API.

This is the machine-readable version of this Firewatch documentation page.

Alert-source adapters normalize vendor webhooks and submit them to:

```text
POST /api/v1/alerts
X-API-Key: fw_<key-id>.<secret>
Content-Type: application/json
```

Create the API key under **Settings → API keys** and configure a
service before sending alerts. The standalone Apache-2.0 `@onfirewatch/sdk`
package contains the typed client, adapter framework, and Prometheus
Alertmanager adapter.

The dashboard's **Alert sources** page generates the configuration for a
selected service and adapter. Its test action sends a real SEV3 event through
the ingestion, incident, escalation, and notification-outbox pipeline.

## Normalized event

```json
{
  "serviceId": "0e48d1d1-a2d6-460b-93a2-cd7a4a86ca0a",
  "source": "prometheus-alertmanager",
  "eventId": "abc123:trigger:2026-07-20T00:00:00.000Z",
  "action": "trigger",
  "deduplicationKey": "abc123",
  "correlationKey": "abc123",
  "title": "Checkout error rate is high",
  "description": "More than 10% of checkout requests are failing.",
  "severity": "SEV1",
  "occurredAt": "2026-07-20T00:00:00Z",
  "labels": {
    "environment": "production"
  },
  "sourceUrl": "https://prometheus.example.test/graph"
}
```

`action` is `trigger` or `resolve`. `eventId` must identify one provider state
transition and remain stable across retries.

## Delivery guarantees

- **Idempotency:** an organization, source, and event ID can be processed once.
  A replay returns the original alert-event and incident identifiers.
- **Deduplication:** firing events with the same source, service, and
  deduplication key attach to the existing active incident.
- **Correlation:** a correlation key connects related trigger and resolution
  events. Resolution events close the correlated active incident.
- **Concurrency:** PostgreSQL transaction-scoped advisory locks serialize both
  event IDs and correlation keys, preventing simultaneous deliveries from
  opening duplicate incidents.
- **Auditability:** normalized alert events are retained in `alert_events`, and
  correlation and resolution changes are appended to the incident timeline.
- **Escalation:** a newly created alert incident uses the service's escalation
  policy and writes notification requests to the same durable outbox used by
  manually created incidents.

The endpoint returns `201 Created` when it creates an incident and `200 OK` for
replays, deduplicated events, resolutions, and unmatched resolutions.

## AWS SNS and SQS

Firewatch also accepts the standard AWS Lambda event envelopes produced by SNS
triggers and SQS event-source mappings:

```text
POST /api/v1/integrations/aws/alerts/<service-id>
X-API-Key: fw_<key-id>.<secret>
Content-Type: application/json
```

Choose **AWS SNS / SQS** on the dashboard's **Alert sources** page to generate a
Node.js Lambda handler. Attach an SNS trigger or an SQS event-source mapping to
that Lambda and store the Firewatch URL, API key, and service ID as Lambda
environment variables.

The adapter accepts batches of up to ten records. It unwraps SNS notifications,
SQS bodies, SNS-over-SQS messages, CloudWatch alarm payloads, and normalized
Firewatch alert objects. CloudWatch `ALARM` creates or correlates an incident;
`OK` resolves it. AWS message IDs provide retry-safe event identity, while alarm
ARNs or names provide the deduplication and correlation key.

This is an alert-source integration only. It does not change
`Queueing__Provider`: the API and worker continue to use the PostgreSQL outbox
unless a deployment separately selects another internal queue implementation.