Threshold Alert Engine

The threshold alert engine monitors your Direct Debit operations in real time and raises alerts when configurable limits are breached. It is built on an Inngest function that is triggered on each relevant event — mandate creation, collection processing, and reserve updates — and evaluates all active thresholds for the organisation at that point.

How It Works

1. A relevant event occurs (e.g. a mandate is created, a collection is submitted, or the clawback reserve changes).
2. The Inngest function is triggered and evaluates all configured thresholds for the organisation.
3. If any threshold is breached, an alert record is written to the alerts table.
4. Email notifications are sent immediately to the org's configured alert recipients.
5. The alert remains active until it is explicitly acknowledged.

Alert Types

Mandate Creation Rate

Raised when the number of mandates created within a rolling 1-hour window exceeds the configured limit.

• Use case: Detect unusual onboarding spikes that may indicate fraud or misconfigured bulk imports.
• Threshold key: mandateCreationRatePerHour

Daily New DD Collection Amount

Raised when the total value of new Direct Debit collections submitted on the current day exceeds the configured limit.

• Use case: Cap daily exposure and flag unexpectedly large collection batches.
• Threshold key: dailyCollectionAmountGBP

Weekly Collection Amount

Raised when the total value of collections over the rolling 7-day window exceeds the configured limit.

• Use case: Provide a broader view of collection volume for risk and compliance monitoring.
• Threshold key: weeklyCollectionAmountGBP

Clawback Reserve Below Minimum

Raised when the balance held in the clawback reserve drops below the configured minimum threshold.

• Use case: Ensure there is always sufficient reserve to cover potential BACS clawbacks before forwarding funds.
• Threshold key: clawbackReserveMinimumGBP

Alert Records

Each alert stored in the alerts table contains:

Field	Description
id	Unique alert identifier
orgId	The organisation the alert belongs to
type	One of MANDATE_CREATION_RATE, DAILY_COLLECTION_AMOUNT, WEEKLY_COLLECTION_AMOUNT, CLAWBACK_RESERVE_LOW
value	The actual observed value that triggered the alert
threshold	The configured limit that was breached
status	active until explicitly acknowledged
createdAt	Timestamp when the alert was raised

Alert Lifecycle

Threshold breached
       │
       ▼
  Alert created (status: active)
       │
       ├──▶ Email sent to configured recipients
       │
       ▼
  Reviewed by operator
       │
       ▼
  Alert acknowledged via API (status: acknowledged)

Alerts are not automatically resolved. An operator must explicitly acknowledge each alert through the API. This ensures that every breach is reviewed before being closed.

Per-Organisation Configuration

Thresholds are configured independently per organisation. Each letting agent (customer) can have different limits based on their portfolio size, risk profile, and compliance requirements. There are no global defaults — thresholds must be set per org.

Email Notifications

When an alert is raised, an email is sent to all recipients configured in the org's alert recipient list. The notification includes the alert type, the observed value, and the threshold that was breached.

To configure alert recipients for an organisation, update the org's alert configuration via the API.

Related

• Clawback Reserve — how the reserve is calculated and maintained
• Alerts API — endpoints for listing and acknowledging alerts