Alert Modes

Alert Mode controls when Extendy GeoShield should require a security alert after a completed WHMCS client-area login event.

Extendy GeoShield does not block login. It evaluates completed login activity, records the event, and then decides whether an alert should be sent according to the configured mode and related settings.

Available modes

The current Alert Mode options are:

Setting label	Stored mode	Summary
Notify on Every Login	every_login	Requires an alert for each detected login country, subject to country-detection failure and cooldown rules
Outside Trusted Countries	outside_trusted_countries	Requires an alert when the detected country is outside the trusted-country model
Smart Mode	smart_mode	Requires an alert when the detected country is new for the WHMCS User and Client Account context

The default mode is Outside Trusted Countries.

Decision flow

At a high level, Extendy GeoShield performs the following work during a normal client-area login:

1. WHMCS completes the login.
2. Extendy GeoShield receives the login event through the WHMCS login hook.
3. The addon excludes admin-as-client / masquerading sessions.
4. The addon resolves the WHMCS User and safe Client Account context where available.
5. The addon resolves the client IP address according to the configured IP source mode.
6. If a public client IP and provider configuration are available, the addon performs a GeoIP country lookup.
7. The addon evaluates the selected Alert Mode, trusted-country state, Smart Mode state, country-detection failure setting, and cooldown window.
8. The Login Events Log is updated with the decision.
9. If the decision requires an alert and a safe Client Account context is available, the addon attempts to send the alert using WHMCS SendEmail.

This process is notification-only. It does not prevent or reverse the WHMCS login.

Notify on Every Login

Notify on Every Login requires a normal login alert whenever a detected login country is available.

Trusted-country rules do not suppress the alert in this mode.

An alert may still be suppressed or skipped when:

• country detection fails and Alert When Country Detection Fails is set to No;
• a previous alert-required event for the same user/client/country key exists inside the configured cooldown window;
• no safe Client Account context is available for email delivery;
• the Client Profile does not have a valid primary email address;
• the Extendy GeoShield email template has copied recipients configured.

The login event is still recorded when processing reaches the event logging flow.

Outside Trusted Countries

Outside Trusted Countries requires a normal login alert when the detected country is outside the trusted-country model for the login context.

The country is treated as trusted when it matches one of the supported trusted-country sources:

• Global Trusted Countries configured by an administrator;
• the current WHMCS Client Profile country for the resolved Client Account.

If the detected country is trusted, the event is logged and the alert decision is suppressed.

If the detected country is not trusted, the normal login alert template is used:

Extendy GeoShield - Login Alert

Smart Mode

Smart Mode requires an alert when the detected country is new for the WHMCS User and Client Account context.

Before sending a Smart Mode new-country alert, Extendy GeoShield still checks:

• Global Trusted Countries;
• the current WHMCS Client Profile country;
• Smart Mode known countries for the exact context.

If the country is already trusted or known for that context, the event is logged and the alert is suppressed.

If the country is new, the Smart Mode template is used:

Extendy GeoShield - Smart New Country Alert

When eligible, this alert can include a trust link that lets the correct authenticated WHMCS User confirm the country for future Smart Mode checks.

For more detail, see Smart Mode.

Country detection failure

The Alert When Country Detection Fails setting controls what happens when Extendy GeoShield cannot determine the login country.

Allowed values are:

• No
• Yes

When set to No, the event is logged, but no client email is sent only because country detection failed.

When set to Yes, the addon uses the normal login alert template with Unknown country values:

Extendy GeoShield - Login Alert

Smart Mode trust links are not generated for Unknown country or country-detection failure alerts.

Cooldown behaviour

The Alert Cooldown setting suppresses repeated alert-required decisions for the same user/client/country key within the configured time window.

The default cooldown is 24 hours. A value of 0 disables cooldown suppression.

Cooldown affects alert sending. It does not remove login event records.

For Unknown country / country-detection failure alerts, cooldown uses an Unknown-country key for the same user/client context.

Recipient behaviour

For the MVP, alert emails are sent to the primary WHMCS Client Profile email address for the safely resolved Client Account.

The WHMCS User email that performed the login is included in the alert content as the login actor.

If no safe Client Account context is available, Extendy GeoShield does not guess a recipient and does not silently send to another Client Account, Contact, or additional copied recipient. The event remains logged, and the email is skipped.

Admin-as-client exclusion

Admin impersonation / Login as Client behaviour is excluded from normal client login alert processing where implemented.

It must not trigger client alerts and must not add Smart Mode known countries.

What Alert Modes do not do

Alert Modes do not:

• block login;
• approve login;
• replace WHMCS authentication;
• prove the visitor is safe;
• change WHMCS Client Profile data;
• send alerts to unrelated contacts or Client Accounts;
• create Smart Mode trust automatically merely because a login occurred.

For the core settings reference, see the Configuration Guide.