WhatsApp Business API integration for operational workflows: what the docs don't tell you

The WhatsApp Business API is a powerful channel for operational alerts, but standard integrations quickly fail when scaling. Meta's webhook system retries failed deliveries aggressively, creating infinite loops of processing overhead if your server fails to return rapid success responses.

The Operational Architecture

To run integrations reliably under production loads, separate the incoming webhook processing logic from actual message queuing. The webhook endpoint must immediately validate payloads, store them to an active queue, and return a clean HTTP 200 OK within 500ms.

Incoming Webhook Processing

Here is the exact PHP webhook controller implementation. It validates incoming signature verification tokens from Meta and immediately schedules the parsing job for background execution.

app/Http/Controllers/WhatsAppWebhookController.php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use App\Jobs\ProcessWhatsAppWebhook;

class WhatsAppWebhookController extends Controller
{
    public function verify(Request $request): Response|string
    {
        $mode = $request->query('hub_mode');
        $token = $request->query('hub_verify_token');
        $challenge = $request->query('hub_challenge');

        // Confirm verify token matches secure config
        if ($mode === 'subscribe' && $token === config('services.whatsapp.verify_token')) {
            return $challenge;
        }

        return response('Unauthorized', 403);
    }

    public function receive(Request $request): Response
    {
        $payload = $request->all();
        
        // Dispatch to queue immediately to release connection
        ProcessWhatsAppWebhook::dispatch($payload);

        return response('EVENT_RECEIVED', 200);
    }
}

Meta Graph API Request Handling

When dispatching outbound template alerts (such as fee reminders and course updates), you must handle Meta's rate limits and token expiry conditions. Wrap API requests in a retry-on-limit block and cache the API response metadata.

app/Services/WhatsApp/WhatsAppClient.php

namespace App\Services\WhatsApp;

use Illuminate\Support\Facades\Http;

class WhatsAppClient
{
    private string $accessToken;
    private string $phoneId;

    public function __construct()
    {
        $this->accessToken = config('services.whatsapp.access_token');
        $this->phoneId = config('services.whatsapp.phone_id');
    }

    public function sendTemplate(string $to, string $templateName, array $parameters): array
    {
        $url = "https://graph.facebook.com/v19.0/{$this->phoneId}/messages";

        $response = Http::withToken($this->accessToken)
            ->retry(3, 100, function ($exception) {
                // Retry if rate limit error code 130 is encountered
                return $exception->getCode() === 130;
            })
            ->post($url, [
                'messaging_product' => 'whatsapp',
                'to' => $to,
                'type' => 'template',
                'template' => [
                    'name' => $templateName,
                    'language' => ['code' => 'en_US'],
                    'components' => [
                        [
                            'type' => 'body',
                            'parameters' => $parameters
                        ]
                    ]
                ]
            ]);

        if ($response->failed()) {
            throw new \Exception('Meta API Error: ' . $response->body());
        }

        return $response->json();
    }
}