API WhatsApp avec Laravel : un webhook signé et une réponse

Pour utiliser l'API WhatsApp depuis Laravel, ajoutez une route d'API pour le webhook et répondez avec le client HTTP. Aucun paquet n'est nécessaire : on vérifie une signature HMAC-SHA256, puis on appelle une API REST avec un jeton.

Mis à jour le 10 novembre 2026Lire en Markdown

La configuration

PHP

// config/services.php'nodium' => [    'key' => env('NODIUM_KEY'),    'webhook_secret' => env('NODIUM_WEBHOOK_SECRET'),],

La route

PHP

// routes/api.phpuse Illuminate\Http\Request;use Illuminate\Support\Facades\Http;use Illuminate\Support\Facades\Route;Route::post('/webhooks/nodium', function (Request $request) {    // The raw body, before any JSON parsing: the signature is computed on it.    $rawBody = $request->getContent();    $timestamp = null;    $signatures = [];    foreach (explode(',', (string) $request->header('X-Nodium-Signature')) as $part) {        [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');        if ($key === 't') $timestamp = (int) $value;        if ($key === 'v1') $signatures[] = $value;    }    if (! $timestamp || abs(time() - $timestamp) > 300) {        return response('', 400);    }    $expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, config('services.nodium.webhook_secret'));    $valid = collect($signatures)->contains(fn ($signature) => hash_equals($expected, $signature));    if (! $valid) {        return response('', 400);    }    $event = json_decode($rawBody, true);    if ($event['event'] === 'message.received' && $event['data']['type'] === 'text') {        Http::withToken(config('services.nodium.key'))            ->post('https://nodium.io/api/v1/messages', [                'channelId' => $event['data']['channel_id'],                'to' => $event['data']['from'],                'type' => 'text',                'text' => 'You wrote: '.$event['data']['text'],                'idempotencyKey' => 'reply-'.$event['id'],            ]);    }    return response('', 200);});

Les routes de routes/api.php ne passent pas par la vérification CSRF, qu'un webhook venu de l'extérieur ne pourrait pas franchir.

Dire à Nodium où vous appeler

Shell

curl https://nodium.io/api/v1/webhooks \  -H "Authorization: Bearer $NODIUM_KEY" \  -H "Content-Type: application/json" \  -d '{ "url": "https://your-app.example.com/webhooks/nodium", "events": ["message.received"] }'# → data.secret (whsec_…): shown once

Ensuite

Écrivez en premier à un client avec un modèle approuvé : le texte libre ne part que dans la fenêtre de 24 heures.
Répondez 200 vite et faites le travail lent ensuite : un événement non acquitté est livré de nouveau, avec le même id.
Branchez les numéros de vos clients avec une clé pour tous.
Pour un travail lent, lancez une tâche en file depuis la route et répondez 200 aussitôt.

Questions fréquentes

Existe-t-il un paquet Laravel pour Nodium ?

Non, et il n'en faut pas : le client HTTP de Laravel et une route suffisent. L'API est décrite en OpenAPI 3.1.