Talk to us
Developer & Infrastructure Engineering

WhatsApp Cloud API Webhook Setup & Troubleshooting Guide

A definitive technical guide to configuring, verifying, and debugging real-time webhooks for inbound customer messages, status callbacks, and button clicks on Meta Cloud API.

1. The Verification Handshake (HTTP GET)

When you enter your Callback URL and Verify Token in Meta Developer Console, Meta sends an immediate GET request with three query parameters:

  • hub.mode: Set to the string subscribe
  • hub.verify_token: The custom secret token you defined in your app
  • hub.challenge: A random integer string generated by Meta

Your server must validate the token and return the raw hub.challenge string as plain text with HTTP status 200:

<?php // Clean PHP Webhook Verification Handler $verifyToken = 'YOUR_CUSTOM_VERIFY_TOKEN_SECRET'; if ($_SERVER['REQUEST_METHOD'] === 'GET') { $mode = $_GET['hub_mode'] ?? ''; $token = $_GET['hub_verify_token'] ?? ''; $challenge = $_GET['hub_challenge'] ?? ''; if ($mode === 'subscribe' && $token === $verifyToken) { http_response_code(200); header('Content-Type: text/plain'); echo $challenge; exit; } http_response_code(403); echo 'Verification token mismatch'; exit; }

2. Top 4 Reasons Webhook Delivery Fails (HTTP POST)

Once verified, Meta streams all inbound chat events via POST. If delivery breaks, check these common pitfalls:

  1. 500 Internal Server Error: Your script crashed when parsing the JSON payload. Always wrap JSON parsing in try...catch blocks and return HTTP 200 immediately.
  2. Timeout (>10s): If your webhook performs slow synchronous database writes, sends emails, or calls other APIs before responding, Meta times out and flags the webhook as failing. Return HTTP 200 first, then process payloads asynchronously.
  3. Invalid SSL/TLS Certificate: Meta strictly requires a valid, trusted HTTPS certificate. Self-signed certificates or broken intermediate CA chains cause silent drop-offs.
  4. Missing Payload Fields: Meta payload structures vary between text messages, button clicks, media uploads, and delivery receipts (sent, delivered, read, failed). Never assume a text.body key exists on every event.

3. Validating Meta Signatures with HMAC SHA-256

To ensure incoming webhooks originate from Meta and not a malicious actor, verify the X-Hub-Signature-256 header:

<?php // Validate SHA256 Signature $appSecret = 'YOUR_META_APP_SECRET'; $signatureHeader = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? ''; $rawPayload = file_get_contents('php://input'); $expectedSignature = 'sha256=' . hash_hmac('sha256', $rawPayload, $appSecret); if (!hash_equals($expectedSignature, $signatureHeader)) { http_response_code(401); die('Invalid payload signature'); } // Payload is authentic - return 200 OK immediately http_response_code(200); echo 'EVENT_RECEIVED';
Developer FAQ

Frequently Asked Questions About WhatsApp Webhooks

Can I test WhatsApp webhooks locally on localhost?+

Yes. Use secure tunneling utilities like ngrok or Cloudflare Tunnel to expose your local development server to an HTTPS endpoint (e.g. https://abc123.ngrok.app/webhook.php) and configure it in Meta Developer Console.

Does NY Digital eliminate the need to manage custom webhooks?+

Yes. NY Digital provides a fully hosted, enterprise-grade webhook consumer cluster that handles millions of messages with automatic retries, deduplication, and immediate routing to your team CRM inbox.

Need enterprise reliability?

Deploy Robust WhatsApp API Infrastructure with NY Digital

Speak with Our Engineering Team
Chat on WhatsApp