Troubleshooting
Most failures are a wrong URL, a missing permission or a blocked outbound connection.
Error messages
| Message | Cause | Fix |
|---|---|---|
| no webhook URL is configured | The provider webhook is empty and the rule has no override. | Add the webhook under Notifications → Configure (Stoat), or fill the rule’s Webhook Override. |
| the webhook URL must be a valid HTTPS URL | Missing scheme, http://, or over 2048 characters. |
Copy the URL from Stoat again and confirm it starts with https://. |
| “host” is not a stoat.chat host | A non-Stoat host was entered without permission. | Use the real URL, or tick Allow Self-Hosted Host for a self-hosted instance. |
| the URL does not look like a webhook URL | The path is not /api/webhooks/{id}/{token}. |
You probably copied the channel URL instead of the webhook URL. Copy it from Webhooks → Copy webhook URL. |
| unexpected port in the webhook URL | A port other than 443 was used without self-hosted mode. | Remove the port, or tick Allow Self-Hosted Host. |
| the webhook was not found (HTTP 404) | The webhook was deleted or recreated, or the URL is truncated. | Create or copy the webhook again and update WHMCS. |
| the webhook token is not valid (HTTP 401) | The token belongs to a deleted webhook, or the URL was copied partially. | Copy the full URL from the channel webhook settings. |
| missing the “SendEmbeds” permission | Format is Embed or Message + Embed but the webhook cannot send embeds. | Grant SendEmbeds, or switch the rule to Message only. |
| missing the “Masquerade” permission | A sender name or avatar is configured but masquerade is not allowed. | Grant Masquerade, or clear Sender Name and Sender Avatar URL. |
| the webhook is rate limited (HTTP 429) | Too many messages, or channel slow mode. | Reduce rule volume, consolidate rules, or wait and retry. |
| could not reach the webhook | DNS, firewall, proxy or TLS problem on the WHMCS server. | Check outbound HTTPS to the Stoat host from the server, including any egress proxy. |
| Stoat returned HTTP 5xx | A Stoat-side outage. | Retry later; the notification is not queued automatically. |
| is not a valid embed colour | The colour is outside Stoat’s CSS grammar. | Use #rrggbb, rgb(), rgba(), a colour name or a gradient, or clear the field. |
| the sender avatar must be an HTTPS URL | Wrong scheme, invalid URL, or over 256 characters. | Use a short HTTPS image URL, or clear the field. |
| the notification was empty | No title, message, URL or embed content was available. | Check the event payload; a rule with no message content cannot be delivered. |
| the payload is too large for Stoat | Unusually large message or attribute set. | Shorten the template or disable attributes for that rule. |
Reading the module log
- Go to Utilities → Logs → Module Log.
- Filter by module
Stoat. - Open the newest entry. The request shows the redacted URL and the payload; the response shows the HTTP status, message ID and error.
- A fallback retry appears as a second entry labelled execute webhook (retry).
If the log has no entry at all, the rule never matched or the provider was not called. Check the rule’s toggle and conditions first.
Message not appearing
- Is the rule enabled? The list toggle must be on.
- Did the event actually fire? Some events run from cron, such as reminders. Confirm WHMCS cron is running.
- Is the condition too narrow? Temporarily remove conditions and retrigger.
- Right channel? A rule override may be sending to a different webhook than you are watching.
- Webhook still exists? A deleted webhook returns 404; the log will show it.
- Duplicate rule disabled? An earlier rule may be matching first and sending elsewhere.
Fallback behaved unexpectedly
When strict delivery is off and a permission is missing, the module strips the rejected feature and retries. That means a message can arrive without its embed or with the webhook’s own sender identity.
- Look for the retry entry in the module log.
- Grant the missing permission to restore the intended appearance.
- Tick Strict Delivery if a degraded message is worse than no message.
TLS and proxy problems
- Self-signed certificates fail verification by design. Install a trusted certificate.
- If the server uses an egress proxy, make sure cURL is configured to use it.
- Test connectivity from the WHMCS server itself, not from your workstation.
Still stuck
Collect the redacted log entry, the exact error text and the WHMCS and PHP versions. Do not include the webhook token. Send them to HardSoftCode support.