Services and alert sources

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:

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