# Services and alert sources

> Model service ownership, assign escalation policies, and ingest alerts safely.

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

## Services

A service is the organization-scoped system affected by an incident. It owns:

- a unique name and optional description;
- one or more primary or secondary owners;
- an optional escalation policy; and
- its incident and alert history.

The member who creates a service becomes its first primary owner. Primary and
secondary are routing labels: both owner types can manage the service, while an
escalation step can specifically target primary owners.

Only responders can create a service or be selected as an owner because owner
targets participate in escalation. Service owners and organization
administrators can edit ownership and routing. Firewatch prevents removal of
the final owner. Archiving a service preserves its history but prevents new
incidents and alert ingestion for that service.

## Assign an escalation policy

Create the policy under **On-call → Escalation policies**, then select it from
the service settings. The assignment is read when a new incident is created.
Existing incidents retain the escalation work already written to the durable
outbox.

Without a policy, Firewatch records the incident but does not page a responder.

## Normalized alert ingestion

External systems submit normalized events to:

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

The organization API key authenticates the sender. The inbound normalized-alert
endpoint does **not** currently add a second HMAC signature scheme. If a vendor
requires signature validation, validate the vendor request in an adapter before
submitting the normalized event with the Firewatch API key.

Important fields have separate jobs:

| Field              | Purpose                                                           |
| ------------------ | ----------------------------------------------------------------- |
| `eventId`          | Stable identity for one provider transition and its retries       |
| `deduplicationKey` | Groups repeated firing events into one active incident            |
| `correlationKey`   | Connects trigger and recovery events when supplied                |
| `action`           | `trigger` creates/correlates; `resolve` closes active correlation |
| `source`           | Stable adapter/provider identifier                                |

Firewatch serializes concurrent events for the same identity and correlation,
stores the normalized event, and returns the original result for an idempotent
replay.

See [Alert adapter integration](/docs/integrations/alert-adapters/) for the
complete payload and AWS envelope behavior.

## AWS SNS and SQS alerts

The **AWS SNS / SQS** source generates a Lambda adapter that forwards an SNS or
SQS event batch to Firewatch. It understands:

- direct SNS notifications;
- SQS messages;
- SNS notifications delivered through SQS;
- CloudWatch alarm state changes; and
- already normalized Firewatch alert objects.

`ALARM` triggers an incident and `OK` resolves it. The Lambda uses a Firewatch
organization API key; Firewatch does not store the alert-source AWS credentials.

This alert source is independent of Firewatch's background-work queue.
Self-hosters can ingest AWS alerts while continuing to use PostgreSQL for
background work.

## Source and recovery links

When provided, `sourceUrl` must be an absolute HTTP or HTTPS URL and is displayed
with the incident's alert event. Treat it as responder-visible data; do not put
credentials or sensitive query parameters in it.