Adding Product Alerting

Adding and extending product alerting

> [!IMPORTANT]

> Use this skill as the recommended engineering starting point whenever a PostHog product is considering adding alerting. Start here before creating a product-local alert framework.

This skill covers two jobs:

• Add platform alerting to a product by composing the shared lifecycle, destination, delivery, scheduling, email, and frontend primitives.
• Extend the alerts platform when a reusable capability, option, or advanced behavior belongs in shared infrastructure.

Route first

| Request | Path | Read |

| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------ |

| Add alerting to a product | Adopt | adopting-platform-alerting.md |

| Build or extend a product alert editor, destination UI, advanced options, or evaluation history | Frontend | frontend-alerting.md |

| Add a lifecycle rule, destination type, delivery behavior, schedule primitive, email capability, wizard option, or shared evaluation feature | Extend | extending-platform-alerting.md |

| Change behavior for one existing product | Adopt first | Keep it product-owned unless the behavior is reusable and backed by a real second use case |

| Understand ownership or choose the correct layer | Architecture | architecture.md |

| Configure or author an existing logs or error tracking alert | Out of scope | Use authoring-log-alerts or authoring-error-tracking-alerts |

| Add real-time in-app notifications | Out of scope | Use sending-notifications |

Platform invariants

Both paths must preserve these rules:

• Evaluation stays domain-specific. Products decide whether their data breached. The shared lifecycle consumes normalized CheckInput.
• One lifecycle machine. Reuse products/alerts/backend/state_machine.py; express real product differences through AlertPolicy, not forks.
• One product mutator. Every persisted state or consecutive_failures write goes through the product adapter's apply_outcome.
• Dispatch and persistence agree. For HogFunction notifications, do not persist a notification-dependent transition until the internal-event producer acknowledges the event. Restore the pre-check outcome when production fails. This acknowledgement does not confirm downstream destination execution.
• Destinations are allowlisted. Shared support does not automatically expose a destination in every product.
• Scheduling math is shared, eligibility is product-owned. Reuse fixed-cadence, calendar-anchor, timezone, and schedule-restriction helpers from products/alerts/backend/scheduling.py. Keep model-specific due predicates and persistence with the adopter.
• Shared code has no product branches. The lifecycle module stays pure Python. Reusable Django behavior belongs elsewhere in products/alerts/backend/.
• Frontend data is normalized at the product boundary. Shared editor components render normalized definitions, destinations, advanced options, schedules, and history. Product API calls, payloads, and evaluation-specific fields stay in the product adapter.
• Defaults remain backward compatible. New platform options must preserve existing adopters until they explicitly opt in.

Current limits

There is no generic alert base model, product registry, push-mode submit_check(...), generic scheduler runner, or generic Temporal harness. Do not invent a parallel framework around those missing pieces. For non-insight products, keep evaluation, persistence, due queries, history, and orchestration in the product until a shared contract lands.

Reference appendix

| Topic | Reference |

| --------------------------------------------------------- | --------------------------------------------------------------------------- |

| Layer ownership, public contracts, and reference adopters | architecture.md |

| Add alerting to a product | adopting-platform-alerting.md |

| Extend shared alert infrastructure | extending-platform-alerting.md |

| Build the product alert frontend | frontend-alerting.md |