Skip to content

WhatsApp Cloud Webhook - Troubleshooting Guide

Problem

Marketing clicks are being received but message.received webhook is NOT being triggered/fired for clicks.

Root Cause Analysis

What We've Verified Already

  1. ✅ Meta webhook subscription includes message_actions field
  2. ✅ Code correctly handles user_actions in payload
  3. ✅ Function deploys successfully
  4. ⚠️ BUT: Webhook events may not be reaching your function OR function may be early-returning

Most Likely Causes

1. Meta Webhook Connection Issue (MOST LIKELY)

After changing webhook fields in Meta Developer Portal: - Meta needs 1-2 minutes to propagate webhook configuration - Existing webhook subscriptions aren't automatically refreshed - Need to verify/re-configure webhook URL on Meta side

Solution: 1. Go to Meta API Dashboard 2. Navigate to WhatsApp → Live Chat → Webhooks 3. Click "Configure Webhook" 4. Important: If you see the webhook field subscription still doesn't include message_actions - Delete/re-create the webhook subscription - OR: Add the fields, then click "Save" and verify connection 5. Test webhook URL under "Webhook Settings" to ensure connectivity

2. Function Not Getting Click Events (HIGH LIKELY)

The webhook might be hitting your function but with a messages event that has empty messages array, causing immediate early return.

Check your Supabase function logs: 

supabase functions logs whatsapp-cloud-webhook --tail

Look for these log patterns: - ✅ Should see: Processing user_action: marketing_messages_link_click - ✅ Should see: Marketing click details: { click_id:... } - ❌ If you see: No messages or user_actions in webhook payload - ❌ If you see: No valid message to process, returning ok

If seeing early-returns, the issue is in Meta webhook configuration (not your code).

3. Channel Account Not Found (MEDIUM LIKELY)

If your WhatsApp Cloud channel's phone_number_id doesn't match Meta's, no channel is found and function throws error.

Check your WhatsApp Cloud channel settings: 

SELECT id, name, type, is_active, settings->>'phone_number_id' as phone_number_id
FROM channel_accounts
WHERE type = 'WHATSAPP_CLOUD'
AND is_active = true;

Important: This must match Meta's metadata.phone_number_id in webhook payload.

4. Context Still Single (LOW LIKELY)

Make sure your edge functions are deployed, not running locally.

Verify deployment: 

supabase functions deploy whatsapp-cloud-webhook --no-verify-jwt

Debugging Steps

Step 1: Verify Webhook is Active

  1. Check Meta webhook logs (Facebook Business Suite → WhatsApp → Live Chat)
  2. Should see webhook pings every few seconds when active
  3. If no pings at all → Webhook not subscribed or URL is wrong

Step 2: Test with curl

Use curl to manually test your webhook with a marketing click payload:

curl -X POST \
 https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-cloud-webhook \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_SUPABASE_SERVICE_ROLE_KEY" \
 -d '{
 "object": "whatsapp_business_account",
 "entry": [{
 "id": "703839838664953",
 "changes": [{
 "field": "messages",
 "value": {
 "messaging_product": "whatsapp",
 "metadata": {
 "display_phone_number": "201271111373",
 "phone_number_id": "YOUR_META_PHONE_NUMBER_ID"
 },
 "user_actions": [{
 "action_type": "marketing_messages_link_click",
 "marketing_messages_link_click_data": {
 "tracking_token": "AI@AQJqgqfnGpRlSAubAblOEKTzbNnGt1-Quw4JacCiTnPs01G7_MlUZ0PHlXgnwmI6UhfKQDWgzvHeBlcqy_lNUpm3",
 "click_id": "IwAR5DmdASMYVg7svyUmugr9yxZ8DGERlUF_hBHxxDCWc6WedyOma6pyS95ennUw_wapm_YTA5NDVhMTUtYzE4Ny00YzljLWE5MmItZDc5YWU1YTM5MGNi_waaem_TmQODyhtIouYTj6PKrsI9A",
 "click_component": "CTA"
 }
 }]
 }
 }]
 }]
 }'

Expected response: 

{"status": "ok"}

Check logs immediately after: 

supabase functions logs whatsapp-cloud-webhook --tail

You should see detailed click processing logs.

Step 3: Check Actual Click Event Payload

What Meta ACTUALLY sends vs what you expect:

Your expected payload (marketing click): 

{
 "value": {
 "user_actions": [{
 "action_type": "marketing_messages_link_click",
 "marketing_messages_link_click_data": {{...}}
 }]
 }
}

What Meta might send (different format): 

{
 "value": {
 "messages": [{
 "from": "919876543210",
 "type": "template",
 "template": {
 "name": "marketing_link",
 "button": {
 "type": "url",
 "url": "https://example.com"
 }
 },
 "interaction": {
 "type": "click",
 "timestamp": 1699999999999
 }
 }]
 }
}

Tip: Get the ACTUAL payload from Meta webhook by implementing a test endpoint or browsing Meta's webhook debug tool.

Step 4: Test with Simple Echo Endpoint

Create a temporary test function to see if Meta clicks are reaching your Supabase: 

// A minimal echo endpoint to confirm Meta's calls are arriving
serve(async (req) => {
 console.log('Test echo received:', JSON.stringify(await req.json, null, 2));
 const body = await req.json;
 return new Response(JSON.stringify({
 success: true,
 received: body.entry?.[0]?.changes?.[0],
 type: body.entry?.[0]?.changes?.[0]?.field
 }), { headers: { 'Content-Type': 'application/json' } });
});

Deploy and test: 

curl -X POST "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/test-echo" \
 -H "Content-Type: application/json" -d '{"test":"value"}'

Then send a marketing click and check if you see it in logs.

What to Tell Meta Developer Support (If Needed)

If the issue persists after all debugging:

  1. Verify webhook fields subscription - explicitly ask them to confirm message_actions is subscribed
  2. Check webhook delivery status - they can see if Meta is sending events
  3. Provide actual webhook payload - Recent payload you received with the click action
  4. Assign case number to Meta API support for WhatsApp Cloud API

Quick Checklist

Before you proceed further:

  • Meta webhook includes message_actions field ✅
  • Webhook URL is correct: https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-cloud-webhook
  • Verify token matches WHATSAPP_CLOUD_VERIFY_TOKEN ✅
  • Check Supabase function logs for clicks (look for user_action)
  • Try sending a marketing click test via WhatsApp Business account
  • Verify click URL is accessible from WhatsApp (actual user clicks on it)

Alternative: Use WhatsApp Cloud API Events Webhook

If Meta's webhook integration continues to be problematic, consider: - Using Meta Business API to query message events periodically - Using third-party webhook monitoring tools - Exporting WhatsApp Business conversations data to your system

This is a temporary workaround while investigating the webhook issue.

Note: The most common issue when checking messages.received webhook after fixing clicks is that Meta is delivering the event as a message_actions event, not a messages event. Your "Get Started" automation or message monitoring might only be listening to messages.received, not message_actions.received.

Check your ConnectGain automation/webhook listeners to ensure they're also subscribed to message_actions event type.