Troubleshooting

The Diagnostics tab is your first stop: callback endpoints, cron heartbeats, queue health, license state and WhatsApp template approval, each section wrapped so one broken subsystem never takes the whole page down. This guide works through the common failures from there.

1. Start at Diagnostics & health

Addons → ImpulseNotify → Diagnostics has three sub-tabs:

• Health Checks — each WhatsApp and SMS channel’s callback URL (and whether a WhatsApp verify token is set), the last verified callback and a lifetime Rejected signatures counter, cron heartbeats, the license state, a queue snapshot with Requeue all dead messages, WhatsApp template approval with Sync WhatsApp templates now, and a phone-number normalizer.
• Activity — this module’s entries in the ImpulseCore audit log, filterable by level, text and time range.
• Help — Impulse Software support contacts, version and system details, and the database schema check.

The module also exposes a JSON health endpoint, which ImpulseCore’s status checks read. It reports counts and ages only — never credentials, recipients or message content:

GET <your WHMCS System URL>/modules/addons/impulsenotify/health.php

{
  "module": "impulsenotify",
  "version": "…",
  "status": "healthy",
  "active_services": 2,
  "queue": { "pending": 0, "oldest_pending_age_seconds": null, "dead": 0 },
  "last_queue_drain_at": "…",
  "last_inbound_process_at": "…",
  "license_check": "ok",
  …
}

license_check reads ok while a valid license is on file. status is healthy, degraded or down. It turns degraded when the oldest pending message has waited more than 15 minutes, when the queue_drain or inbound_process heartbeat is more than 10 minutes old, when dead-lettered messages exist, or when the schema version is missing; the reasons are listed in degraded_reasons.

2. “Dev mode is limited to …”

The install has no valid license, so it’s running in dev mode: every feature works, but creating more than 3 channels, 5 rules or 2 staff recipients is refused, and sends stop once 50 have gone out in the current UTC day (the count resets at 00:00 UTC). Settings → Licence & limits shows usage against each cap (its sends figure is an approximate 24-hour count; the cap counts every send, test sends included, in the UTC day).

Add your INTFY- key under ImpulseCore → Modules & Licensing → Licenses; the caps lift as soon as Core validates it. If a key is on file but the Dashboard still reads dev mode, check the key’s status in ImpulseCore — a license that lapses past its grace period returns the install to dev mode. Existing channels, rules and recipients are never removed by the caps.

3. Messages sit pending, never deliver

The queue isn’t being drained. Queued delivery, retries and the domain and SLA scans run as ImpulseCore cron tasks.

• Diagnostics → Health Checks → Cron heartbeats — a stale queue_drain heartbeat is the tell.
• Check that ImpulseCore’s cron runner is installed and ticking: ImpulseCore → Operations → Cron shows the crontab line and the last tick. queue_drain and inbound_process want a * * * * * schedule; on a 5-minute schedule, messages wait up to 5 minutes.
• Make sure the PHP binary in the cron line has the ionCube Loader too — /opt/plesk/php/8.3/bin/php on Plesk, /opt/cpanel/ea-php83/root/usr/bin/php on cPanel, or /usr/bin/php on a plain Linux server.
• Check that Pause ALL sends under Settings → Delivery controls is off: while it’s on, queued messages wait.

4. WhatsApp / SMS stay sent, never delivered

The messages left your server; the provider’s delivery receipts aren’t landing.

• Confirm the channel’s callback URL is publicly reachable over valid, not self-signed, HTTPS — no password prompt, IP allowlist or maintenance page in front of /modules/ paths.
• For WhatsApp, confirm the messages webhook field is subscribed and the app is subscribed to the business account — re-running Auto-configure repairs both. See the WhatsApp troubleshooting matrix.
• For SMS, paste the URL from SMS callback endpoints into the provider console exactly as shown, as an HTTP POST webhook. AWS SNS sends no receipts to the module at all.
• Watch Last verified callback received — it updates the moment a signed receipt lands.

5. Rejected signatures keeps climbing

Genuine callbacks are arriving but failing signature verification, so the module refuses them (HTTP 403). Re-enter the secret on the channel:

• WhatsApp: copy the App secret again from Meta’s App settings → Basic.
• SMS: the credential that verifies the provider’s callbacks — the Twilio or Plivo auth token, the Vonage signature secret, the Telnyx public key, or the MessageBird signing key.

This is the module protecting you

A valid signature is required before ImpulseNotify parses or stores any callback, so with a wrong secret, status updates never touch your database. Fix the secret and the counter stops climbing.

6. A WhatsApp message is never sent

WhatsApp sends only Meta-approved templates, checked when a message is queued. Check Diagnostics → Health Checks → WhatsApp template approval and run Sync WhatsApp templates now: only approved templates are queued — pending, rejected, paused and not synced aren’t. In this release only the diagnostics test template is linked, so rule-routed events and client verification codes on WhatsApp are skipped; see WhatsApp onboarding.

7. Diagnostics shows (SystemURL missing)

A callback URL reads (SystemURL missing) because WHMCS’s System URL isn’t set. Set System URL under System Settings → General Settings to your public HTTPS address — the module builds every callback URL from it, and Auto-configure needs it.

8. A rule never fires

Check, in order:

• The rule is Enabled and its channel is enabled.
• Its pattern matches a real event — a “matches no known event” warning means it stays silent. invoice.overdue and the failed-login events are in the catalog but aren’t emitted yet.
• ImpulseNotify is active in ImpulseCore (ImpulseCore → Modules & Licensing → Modules). The Dashboard’s registered only means Core knows the module; the WHMCS hooks stay silent until Core lists it as active.
• Diagnostics → Activity — a matched event leaves a notify.ingest entry whose suppressed counts say why nothing was sent:

Reason	Meaning / fix
no_template	No template for this event on this channel type — see Templates. Webhook channels need none.
no_contact / unverified	Client audience: the client has no contact, or no verified contact, for this channel type.
no_consent	Client audience: the client has switched this category off on this channel type, or replied STOP.
no_admin_recipients	Admin audience: no enabled staff recipient matches the category with an address for this channel.
wa_unapproved	The WhatsApp template isn’t approved.
rate_limited / dev_send_limit	A rate limit or the dev-mode daily cap was reached; the message was dropped, not queued.
dry_run	Dry-run mode is on.
duplicate	A message with the same key was already queued today — a double-fired hook, or the same event on the same record again (such as a second reply on one ticket).

New events are dropped while Pause ALL sends is on, and leave no entry.

9. Telegram linking or STOP replies do nothing

Both need Telegram to deliver updates to the module, which needs a webhook registered with Telegram’s setWebhook — the module doesn’t register it for you. Check the URL ends in callbacks/telegram.php?channel=<id> for the right channel and that its secret_token matches the channel’s webhook secret; a mismatch is refused. The Connect Telegram button only appears on the client-area page while a Telegram channel is enabled. See Connecting channels.

10. Dead-lettered messages

A message whose temporary failures outlast its retries (60s → 5m → 15m → 1h → 6h, dead-lettered at attempt 6) lands in the dead state. Check the error on its Logs row, fix the cause, then requeue it: the per-row Requeue on the Logs tab (offered only while the message is still dead), or Requeue all dead messages in Diagnostics → Health Checks.

Reading the Logs tab

The log is append-only — one row per delivery attempt or receipt. Filter by status and by day window. sent = handed to the provider; delivered = a receipt confirmed it (a separate row after the sent row); failed = a failed attempt — temporary failures are retried, and a dead-lettered message’s last attempt shows failed with a Requeue button; skipped = dry-run, or a fallback hop made redundant by delivery on another hop. Matches suppressed before queuing (no template, rate limit and so on) appear only under Diagnostics → Activity. Recipients are stored masked — the log outlives consent by design. Channel test sends aren’t logged here.

11. Everything is in the audit log

Module events are written to the ImpulseCore audit log, viewable under Diagnostics → Activity (or ImpulseCore → Operations → Audit). Settings saves record which settings changed, and channel, rule and staff-recipient changes are all logged — so when a delivery problem is really a configuration change, the log shows what changed and when. Credentials are scrubbed from every entry, and recipient fields are masked.

12. Still stuck?

Contact Impulse Software support at support.impulsesoftware.com or [email protected]. Include the module version from Diagnostics → Help and the relevant Activity entries.