Apsona API Governance & Alert System #

The Apsona API Alert System is an event-based monitoring utility designed to alert administrators when Salesforce Org-wide API consumption reaches user-defined thresholds.
Unlike a continuous monitor, this system executes only during the processing of triggered records. It provides a governance layer that evaluates current Org health at the moment of execution to determine if a transaction should proceed or if an alert should be dispatched.

Core Functionality

• On-Demand Evaluation: API consumption is checked only when the ApsonaTriggerMerge or related services are actively processing records.
• Threshold-Based Alerting: Dispatches notifications when consumption levels reach “Moderate” or “Critical” stages.
• Hard Stop Enforcement: Once the Critical threshold is reached, the system stops accepting new merge requests to prevent further strain on the Org.

Important Constraints

• Reactive Monitoring: This system does not monitor API usage in real-time outside of Apsona-related transactions.
• No Absolute Guarantee: While the system stops accepting new requests after the Critical threshold is met, it cannot revoke callouts already in flight or stop consumption from other Org processes. Therefore, reaching a threshold does not strictly guarantee that the Org will stay below that specific API limit.

Severity Level Definitions #

Severity	Definition	System Action
Moderate	User-defined warning threshold.	Notify only. Informs users that consumption is high, but continues processing new requests.
Critical	User-defined “Hard Stop” threshold.	Notify & Abort. Stops accepting new merge requests and alerts users that the threshold has been breached.

Dynamic Severity Levels #

The system categorizes Org health into four distinct states. These states determine whether the integration remains active and which stakeholders are notified.

Severity	Threshold (Default)	System Action	Notification Behavior
Normal	< 85%	Full Operation. All requests processed.	None (Silent).
Moderate	85% – 94%	Active Monitoring. Operations continue.	Warning sent to “Moderate” permission holders.
Critical	≥ 95%	Circuit Breaker Trip. All outbound requests aborted.	Urgent alert sent to “Critical” permission holders.

Key Features #

Configurable Settings: You can customize the system without any code changes: #

• Set your own Moderate and Critical thresholds
• Choose notification channels:
  • Email
  • Slack
  • Salesforce notifications (bell icon)
• Update Slack/webhook destinations easily

Smart Alerting (No Spam):The system avoids sending repeated alerts for the same condition. #

• Alerts are sent only when the severity level changes
• Example:
  • Normal → Moderate → sends alert
  • Staying in Moderate → no repeated alerts
  • Moderate → Critical → sends alert

This keeps notifications meaningful and actionable.

Notification Access & Permission #

Alerts are sent based on custom permissions, giving you flexible control over who gets notified.

You can assign:

• Apsona_Moderate_Alert
  → Receives warning notifications
• Apsona_Critical_Alert
  → Receives critical alerts and escalation notifications

This allows you to route alerts to the right users without relying on fixed user lists or groups.

Summary

The Apsona API Governance & Alert System helps you:

• Monitor API usage at the right time
• Get early warnings before limits are reached
• Automatically prevent overload during critical situations
• Control alerts and thresholds based on your needs

One-Time Setup Guide: Alert Service #

Setting Consumption Thresholds #

The system uses “Moderate” and “Critical” thresholds to determine when to warn users and when to trigger the circuit breaker. If these are not defined, the system defaults to 85% (Moderate) and 95% (Critical).

1. Navigate to Setup → Custom Metadata Types.
2. Locate Apsona API Limit Configuration and click Manage Records.
3. Click Edit next to the Default record.
4. Modify the following fields:
   • Moderate Threshold: The percentage (e.g., 80) at which warning alerts are sent.
   • Critical Threshold: The percentage (e.g., 95) at which the system will stop accepting new merge requests.
5. Click Save.

Best Practices for Thresholds #

• The “Safety Buffer” Rule: Always leave at least a 5–10% gap between your Moderate and Critical thresholds. This gives your team enough time to pause non-essential bulk jobs before the system hits the Hard Stop.
• Non-Retryable Logic: Remember that once the Critical threshold is met, Apsona stops accepting requests. These requests are not automatically queued or retried. Ensure your Critical threshold is high enough that it only triggers in true emergencies to avoid manual re-processing of business data.

Configuring Alert Channels #

Activation (Metadata Setup) #

Before configuring the technical “plumbing,” you must tell the system which channels should be active for each severity level.

1. Navigate to Setup → Custom Metadata Types.
2. Locate Apsona API Alert Config and click Manage Records.
3. You will see two records: Moderate Alert and Critical Alert.
4. Edit each record and check the boxes for the channels you wish to use (Email, Bell Notification, or Slack).
5. Save your changes.

Channel-Specific Configuration #

Once the boxes are ticked, follow the steps below for each enabled channel to ensure alerts are delivered successfully.

Email: The “Deliverability” Stack #

Salesforce requires a verified identity to send automated emails. Without these steps, alerts may be blocked by spam filters or fail to send entirely.

• • A. Set up an Organization-Wide Address:
    • Go to Setup → Organization-Wide Addresses and click Add.
    • Display Name: e.g., “Salesforce API Monitor”.
    • Email Address: Use a monitored inbox (e.g., it-alerts@yourcompany.com).
    • Purpose: Select “User Selection and Default No-Reply Address.”
    • Verification: You must log into that inbox and click the verification link sent by Salesforce.
  • B. Configure the Process Automation User:
    • Go to Setup → Process Automation Settings.
    • In the Automated Process User Email Address field, enter the Organization-Wide Address you just verified.

• Why this matters: System-triggered alerts often run under the “Automated Process” user. If this user has no verified email, the alert will fail silently.

Slack: The Webhook Workflow #

This requires “whitelisting” Slack so Salesforce is allowed to send data to it.

• A. Generate a Slack Webhook URL: slack documentation link
• B. Update Remote Site Settings (Mandatory):
  • Go to Setup → Remote Site Settings → New Remote Site.
  • Remote Site Name: Slack_API.
  • Remote Site URL: https://hooks.slack.com.
  • Why this matters: Salesforce blocks all outbound traffic by default.
• C. Map the URL:
  • Return to your Apsona API Alert Config metadata record and paste the URL into the Slack Webhook URL field.

 

Defining Who Receives Alerts #

Use Provided Permission Sets  #

To prevent notification noise for all users, alerts should be selectively routed to specific teams who can take actionable steps. 

Apsona includes pre-built Permission Sets for easy assignment

1. Go to Setup → Permission Sets.
2. Locate Apsona Moderate Alert Access or Apsona Critical Alert Access.
3. Locate Apsona Moderate Alert Access or Apsona Critical Alert Access  & Click on  Manage  Assignments
4. Click Manage Assignments and add the relevant users.

Follow the same steps to assign user to Apsona Critical Alert Access.

Optional Setup: Platform Cache #

To allocate memory:

1. Go to Setup → Platform Cache.
2. Locate the existing partition named ApsonaCache.
3. Click Edit.
4. In the Org Cache Allocation section, allocate at least 1MB
5. Click Save.

Why do this?

• Reduces SOQL Usage: By storing the severity state in the cache, the system avoids redundant database lookups.
• Faster Execution: Memory retrieval is significantly faster than database queries, ensuring the API check adds negligible overhead to your merge processes.
• Optional: If you do not allocate memory, the system will simply default to standard database queries to track alerts.