RocketChat/Rocket.Chat · error · Error

error-invalid-webhook-response

error-invalid-webhook-response

Error message

error-invalid-webhook-response

What it means

Catch-all thrown by POST /api/v1/livechat/webhook.test: any failure while POSTing the sample payload to Livechat_webhookUrl — DNS resolution failure, TLS error, timeout, oversized response (fetch size cap is 10MB), or the inner 'Invalid status code' for non-200 replies — is logged and re-thrown as error-invalid-webhook-response. The original cause is only visible in the server logs (WebhookTest logger.error), not in the API response.

Solutions

1. From the Rocket.Chat server host (not your laptop), curl -i the Livechat_webhookUrl with the sample payload — this reproduces DNS/TLS/egress problems the API test hides
2. Check the server logs: the WebhookTest logger records the exact underlying error (ENOTFOUND, CERT_HAS_EXPIRED, socket hang up, ...)
3. If curl from the server works but the test still fails, compare response status and size — must be 200 and under the 10MB read cap

import { lookup } from 'node:dns/promises';
// cheap pre-flight from the Rocket.Chat host's network position
await lookup(new URL(webhookUrl).hostname); // throws ENOTFOUND early instead of inside webhook.test

wrap webhook.test in a retry with capped backoff (e.g. 3 attempts, 5s apart) but only for transient causes — re-run after confirming DNS/TLS from the server host; a deterministic non-200 receiver will fail every time, so fix the endpoint instead of retrying.

When it happens

Trigger: POST /api/v1/livechat/webhook.test with Livechat_webhookUrl unreachable (wrong DNS, expired cert, firewall blocking the server's egress), a URL that returns non-200, or a handler that hangs until the fetch times out. If Livechat_webhookUrl is unset you get 'Webhook_URL_not_set' instead — this error implies a URL was configured.

Common situations: Webhook URL from a local tunnel (ngrok-style) that expired; self-signed certificate on the receiver; server egress restricted so it can't reach an internal service; receiver slow to respond and connection reset mid-test.

Related errors

• Invalid status code
• agent-not-found
• Attachments should be Array, ignoring value
• cannot-access-room
• department-not-found

AI-assisted analysis of RocketChat/Rocket.Chat@b2c16d5842 (2026-08-18). Data as JSON: /api/errors/161f38b1745d3147. Report an issue: GitHub.

Appendix: source

Thrown at apps/meteor/server/api/v1/omnichannel/webhooks.ts:91

			if (!webhookUrl) {
				return API.v1.failure('Webhook_URL_not_set');
			}

			try {
				logger.debug({ msg: 'Testing webhook', webhookUrl });
				const request = await fetch(webhookUrl, options);
				const response = await request.text();

				logger.debug({ msg: 'Webhook response', response });
				if (request.status === 200) {
					return API.v1.success();
				}

				throw new Error('Invalid status code');
			} catch (error) {
				logger.error({ msg: 'Error testing webhook', err: error });
				throw new Error('error-invalid-webhook-response');
			}
		},
	},
);

View on GitHub (pinned to b2c16d5842)