Home › Troubleshooting

Troubleshooting

Every failure names the next action. Start with the exact error in the provider dialog or the module log.

First checks

Save the provider once. The connection test runs immediately and reports the real error in the dialog.
Enable module logging under Configuration → System Logs → Module Log, trigger a test event, then read the Microsoft Teams entry.
Confirm the channel still exists. A deleted channel, removed workflow or revoked connector returns 401, 403, 404 or 410.
Check the URL in use. If the failing rule sets Webhook Override, the provider webhook may be fine and the rule URL may be wrong. The module log shows the redacted URL that was called.
Check outbound HTTPS from the WHMCS server to the webhook host on port 443.

Saving sends a real message — the connection test posts a card to the channel. Warn channel members before you save if the channel is busy.

Error reference

Message	Cause	Fix
`no webhook URL is configured`	The provider has no URL, or a rule is using a provider row that was never configured.	Open the provider dialog and paste the Workflows trigger URL or legacy Incoming Webhook URL.
`the webhook URL must be a valid HTTPS URL`	The URL is empty, malformed, or uses `http`.	Copy the full URL from Teams; it must start with `https://`.
`must not contain credentials` / `must not contain a fragment`	The URL has `user:pass@` or a `#` fragment.	Use the plain URL generated by Teams.
`is not a Microsoft Teams or Power Automate host`	The host is outside the allowlist.	Use the real Teams URL, or enable Allow Custom Host only for a national cloud or trusted proxy.
`a legacy Incoming Webhook URL must not contain a query string`	A Workflows URL was pasted but its host was recognised as legacy, or extra parameters were appended.	Copy the URL again without editing it.
`does not look like an Incoming Webhook URL`	A legacy host is used without `/webhook/` or `/webhookb2/` and `/IncomingWebhook/`.	Use the full connector URL, not the channel URL.
`Workflows trigger URL is missing its signature query string`	The `?api-version=...&sig=...` part was dropped.	Copy the complete HTTP POST URL from the workflow trigger.
`does not look like a Workflows trigger URL`	The URL is a workflow designer link or a channel link, not the trigger endpoint.	Use the URL shown under When a Teams webhook request is received.
`unexpected port in the webhook URL`	The URL specifies a port other than 443.	Remove the port, or enable Allow Custom Host for a trusted proxy.
`rejected the message payload (HTTP 400)`	Teams or the workflow rejected the card shape, or the URL is not a webhook endpoint.	Confirm the URL; retry with Hide Attributes ticked to isolate a field problem.
`did not authorise the webhook (HTTP 401)`	The workflow or connector was revoked, expired or regenerated, or the stored URL was HTML-escaped repeatedly (`&` layers).	Version 1.3.0 decodes repeated `&` escapes automatically. If it still fails, copy the trigger URL again from Power Automate and paste it into the provider field.
`refused the request (HTTP 403)`	Connectors or Workflows are disabled for the tenant, team or channel, or the owner lost access.	Ask a Teams administrator to allow the feature; confirm the workflow is still enabled and has an owner.
`webhook was not found (HTTP 404)`	The workflow, connector or channel was deleted.	Recreate the webhook and paste the new URL.
`webhook has been removed (HTTP 410)`	Microsoft retired or removed the connector.	Move to a Teams Workflows trigger.
`payload is too large (HTTP 413)` or `notification payload is too large to send`	The card exceeds the Teams size limit.	Tick Hide Attributes, shorten the message, or choose Message only.
`rate limiting this webhook (HTTP 429)`	More than about four requests per second, or the per-minute and per-hour thresholds were reached.	Reduce rule volume, consolidate events, or retry later.
`returned HTTP 5xx`	A transient Microsoft service error.	Retry later; check the Microsoft 365 service health dashboard.
`could not resolve the webhook host (cURL 6)`	DNS failure on the WHMCS server.	Check `/etc/resolv.conf` or the Windows DNS client and try again.
`could not connect to the webhook host (cURL 7)`	Outbound HTTPS is blocked by a firewall, proxy or SELinux policy.	Allow port 443 to the Teams or Power Automate host.
`request timed out (cURL 28)`	The network is slow or the host is unreachable.	Increase Request Timeout (maximum 30) and check connectivity.
`TLS handshake failed` / `TLS certificate could not be verified`	The server CA bundle is outdated, or a TLS-intercepting proxy is present.	Update the CA bundle and the server clock; do not disable certificate verification.
`is not a valid theme colour`	The rule uses a colour name or an invalid hex value.	Use six hex digits with or without `#`, for example `#0076D7`.
`the card icon must be a valid HTTPS image URL`	The Card Icon URL is HTTP, malformed or longer than 512 characters.	Use a publicly reachable HTTPS image URL, ideally about 200×200.

Reading the module log

Enable logging under Configuration → System Logs → Module Log. A delivery entry contains:

Module — Microsoft Teams.
Action — execute webhook or execute webhook (retry).
Request — the redacted URL and the JSON payload.
Response — HTTP status, error text and a truncated response body.

The URL ends in [redacted], and a Workflows signature is replaced by ?[redacted]. If you see a full token in the log, stop and rotate the webhook.

No card appears, but the log says Sent

Confirm the workflow is enabled and posts to the channel you are watching.
Check the workflow run history in Power Automate for a failed action.
Confirm the card was not posted in a private channel you cannot see.
Check whether a Teams filter or notification setting hides the card.

Legacy connector shows 410 or 404

Microsoft retired Office 365 connectors in Teams in May 2026. A legacy Incoming Webhook may stop working even though the URL is unchanged. Create a workflow from the When a Teams webhook request is received trigger, replace the provider URL and save. The MessageCard payload does not need to change.

Before contacting support

Copy the exact error text and the HTTP status.
Copy the redacted module log entry.
State the WHMCS version, PHP version and whether the URL is Workflows or legacy.
Never include the real webhook URL, token or signature.