WhatsApp Cloud Webhook — Troubleshooting¶

Messages you send from ConnectGain go out through Meta's API directly. Everything that comes back — inbound messages, delivered/read receipts, and marketing-message link clicks — arrives through the webhook Meta calls. When any of those stop, the webhook is almost always the reason.

This page is for numbers connected manually with a system user, where you configured the webhook in your own Meta app (see step 6 of that guide). Numbers connected through the Facebook wizard use ConnectGain's webhook automatically; if one of those stops receiving, skip to Still not working.

On this page: Symptoms · Check the channel · Check the webhook on Meta · Marketing clicks · Test it · Still not working

Symptoms¶

What you see	What it usually means
Sends work, but replies never appear in the inbox	The webhook is not configured, not verified, or points at the wrong URL
Messages show Sent but never Delivered or Read	Same — statuses only arrive through the webhook
Replies arrive, but link clicks on marketing messages are not recorded	The `message_actions` field is not subscribed
Everything stopped after you changed something in the Meta app	Meta takes a minute or two to apply webhook changes, and sometimes needs the subscription saved again

1. Check the channel in ConnectGain¶

Open Settings → Channels and find the WhatsApp Cloud channel.

It must show as Active. A paused or disconnected channel receives nothing.
The phone number on the channel must be the same number Meta sends events for. If you reconnected the number or moved it between WhatsApp Business Accounts, reconnect the channel so the two match again.
The channel card shows the number's health (display-name review, billing, restrictions). A number that cannot send may still receive — see WhatsApp Cloud send blocks for those cases.

2. Check the webhook on Meta¶

In the Meta App Dashboard: WhatsApp → Configuration → Webhook.

Callback URL — the ConnectGain WhatsApp Cloud webhook address shown on the channel's connection screen. Copy it again rather than retyping it.
Verify token — the exact string you typed into ConnectGain when you connected the number. It is a value you invented, not something Meta gives you. If they differ, Meta cannot verify the URL and delivers nothing.
Subscribed fields — at least messages. Click Manage and make sure it is ticked.
After any change, click Verify and save, wait one to two minutes, then test again. If events still do not arrive, remove the subscription and add it again: Meta does not always refresh an existing subscription when its fields change.

Pointing the number at ConnectGain from the channel's Webhooks tab. Open the channel (Settings → Channels, edit the WhatsApp Business channel) and choose Webhooks. Click Use ConnectGain webhook to fill in the callback address. When the address is ConnectGain's own, there is no Verify token box: ConnectGain supplies the token itself, so you have nothing to type and nothing to match. Earlier versions asked for one, and whatever was typed was rejected, so Meta refused the change with error #2200. If you still see that error after clicking Use ConnectGain webhook, reload the page and try again. The Verify token box appears only when you enter a different callback address of your own; in that case you choose the token, and your server must return it when Meta asks.

3. Marketing-click events need one more field¶

Clicks on the buttons of marketing messages are delivered as a separate event type. To record them, subscribe the webhook to message_actions as well as messages, save, and re-test after a couple of minutes. Without it, replies arrive normally but clicks are never reported.

4. Test it¶

From a personal phone, send a message to the business number. It should appear in the inbox within a few seconds.
Reply from ConnectGain. The message should move to Delivered, then Read once opened.
For marketing messages, tap a button in the received message and check the contact's activity for the click.

If step 1 fails, the webhook is not reaching ConnectGain — go back to section 2. If only step 3 fails, it is the message_actions field.

Still not working¶

Contact support with:

the business phone number and the channel name in ConnectGain,
the time (with timezone) of a test message that did not arrive,
a screenshot of the Meta webhook configuration page (callback URL and subscribed fields).

Support can see whether Meta's calls reached ConnectGain and what happened to them.