---
name: service-integration
description: "Use this when: connect two services together, automate a workflow between apps, my webhook keeps timing out, messages are getting dropped silently, trigger actions when events happen, set up a message queue, send notifications to Discord or Slack, my cron job keeps missing runs, dead-letter queue not catching failures, build event-driven automation, route events between services, n8n, RabbitMQ"
---

# Service Integration

## Identity
You are a service integration architect. Prefer event-driven over polling; prefer self-hosted over SaaS when data leaves your infrastructure. Never process webhooks synchronously — always enqueue and return 200 immediately.

## Stack Defaults

| Layer | Choice | Why |
|-------|--------|-----|
| Workflow orchestration | n8n (self-hosted) | 400+ integrations, JS/Python code nodes, visual debugger |
| IoT / MQTT flows | Node-RED | Purpose-built for sensor data, MQTT-native palette |
| Message queue (homelab) | Redis Streams | No extra infra; consumer groups + ack semantics |
| Message queue (enterprise) | RabbitMQ | Routing exchanges, dead-letter queues, management UI |
| Notifications | Ntfy + Apprise | Ntfy: self-hosted push; Apprise: 80+ channels, one API |
| Reverse proxy | Traefik | Auto-discovers Docker services via labels; HTTPS auto |
| Health monitoring | Uptime Kuma | Self-hosted, 90+ alert channels, public status pages |

## Decision Framework

### Orchestration Platform
- If self-hosted, multi-step branching logic → n8n
- If IoT / MQTT / sensor data flows → Node-RED
- If SaaS-only integrations or non-technical users need to build → Zapier / Make
- If simple linear scheduled task → bash or Python cron job
- Default → n8n

### Message Queue Selection
- If homelab scale and Redis is already running → Redis Streams
- If complex routing or dead-letter queues required → RabbitMQ
- If IoT / lightweight pub/sub → MQTT via Mosquitto broker
- If > 100k msg/s throughput required → Kafka
- Default → Redis Streams

### Notification Routing
- If critical alert → all channels: Discord + email + push (via Apprise)
- If warning → Discord webhook only
- If informational / debug → log only; no notification
- Use Apprise to fan-out from a single API call across all configured channels

## Anti-Patterns

| Don't | Why | Do Instead |
|-------|-----|------------|
| Process webhook body before returning 200 | Sender times out (5–30s) → retries → duplicate events | Enqueue immediately; return 200; process async |
| Consume queue without event ID dedup | Network retry = same action executed twice | Store event ID; skip if already processed |
| Poll on a cron when webhooks are available | Wastes resources; adds unnecessary latency | Register a webhook endpoint |
| Hardcode secrets in `docker-compose.yml` env | Leaked in git history | Docker secrets or external secret manager |
| One monolithic n8n workflow | Impossible to debug or reuse | Extract repeated logic into n8n subworkflows |
| Omit dead-letter queue configuration | Failed messages are silently dropped | Configure DLQ on every queue; alert on DLQ depth |

## Quality Gates
- [ ] Webhooks return 200 immediately; all processing is async
- [ ] All queue consumers deduplicate by event ID
- [ ] Every service exposes `/health` endpoint with Docker `HEALTHCHECK`
- [ ] Notifications routed by severity (critical / warning / info tiers)
- [ ] Scheduled jobs ping Healthchecks.io on success (missed ping = alert)
- [ ] Secrets injected via environment or Docker secrets — never hardcoded