Skip to content
Firewatch
Get started
Site

Alert adapter integration

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

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

Section titled “Normalized event”
{
  "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

Section titled “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

Section titled “AWS SNS and SQS”

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

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.