Pular para o conteúdo
apiwpp
Integração

Integração do WhatsApp com Laravel: Http facade, Jobs e webhook assinado

Integre o WhatsApp ao Laravel: envio com o Http facade em Jobs com clientRef, rota de webhook com middleware de assinatura e eventos em fila.

Atualizado em

No Laravel, a apiwpp não precisa de pacote: o Http facade envia as mensagens, os Jobs cuidam das retentativas e um middleware confere a assinatura dos webhooks. Esta página junta as peças num desenho que aguenta produção: configuração no lugar certo, envio fora da requisição do usuário, retentativas sem mensagens duplicadas e eventos processados na fila. Para o mesmo fluxo com todos os detalhes, o tutorial integração do WhatsApp com PHP e Laravel vai passo a passo.

Configuração: .env e config/services.php

Guarde a chave de API (escopo messages:send), o id da conexão e o segredo do webhook no .env, e leia tudo por config(). Com php artisan config:cache, o .env deixa de ser lido em tempo de execução, e um env() fora dos arquivos de configuração devolve null.

# .env
APIWPP_URL=https://api.apiwpp.com
APIWPP_KEY=wag_live_...
APIWPP_CONNECTION_ID=8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f
APIWPP_WEBHOOK_SECRET=cole-aqui-o-segredo-do-projeto
// config/services.php
'apiwpp' => [
    'url' => env('APIWPP_URL', 'https://api.apiwpp.com'),
    'key' => env('APIWPP_KEY'),
    'connection_id' => env('APIWPP_CONNECTION_ID'),
    'webhook_secret' => env('APIWPP_WEBHOOK_SECRET'),
],

Se cada cliente do seu sistema tem o próprio número, o id da conexão sai do banco, não do .env. A chave é por projeto, e as chaves podem ser rotacionadas com um período de sobreposição, sem parar o envio.

Um cliente pequeno com o Http facade

Uma classe concentra a URL, a chave e o tempo limite, e devolve a Response para quem chamou decidir o que fazer:

<?php

namespace App\Services;

use Illuminate\Http\Client\Response;
use Illuminate\Support\Facades\Http;

class Apiwpp
{
    public function send(string $connectionId, array $payload): Response
    {
        return Http::baseUrl(config('services.apiwpp.url'))
            ->withToken(config('services.apiwpp.key'))
            ->acceptJson()
            ->timeout(15)
            ->post("/connections/{$connectionId}/send", $payload);
    }
}

POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt (milissegundos unix) e position. O corpo leva to (só dígitos, com país e DDD), message e o clientRef. Mídia vai em media, com type e uma url https pública.

Enviar a partir de um Job, com clientRef

O envio não deve travar a requisição do usuário. O controller despacha um Job, e o worker chama a API. O Laravel repete Jobs que falham, e uma falha depois de a apiwpp ter aceitado o envio (um tempo esgotado na resposta, por exemplo) mandaria a mensagem duas vezes. O clientRef evita isso: uma repetição com o mesmo valor, na mesma conexão, responde 200 com o job original e "duplicate": true, sem enfileirar nada, por até 7 dias.

<?php

namespace App\Jobs;

use App\Services\Apiwpp;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use RuntimeException;

class SendWhatsApp implements ShouldQueue
{
    use Queueable;

    public int $tries = 6;

    public function __construct(
        public string $connectionId,
        public string $to,
        public string $message,
        public string $clientRef, // e.g. "pedido-1234-envio": stable across retries
    ) {}

    public function backoff(): array
    {
        return [5, 15, 60, 300, 900];
    }

    public function handle(Apiwpp $apiwpp): void
    {
        // A timeout throws ConnectionException and the Job is retried with the same clientRef
        $response = $apiwpp->send($this->connectionId, [
            'to' => $this->to,
            'message' => $this->message,
            'clientRef' => $this->clientRef,
        ]);

        if ($response->successful()) {
            return; // 202 queued, or 200 with duplicate: true
        }

        if ($response->status() === 429) {
            $this->release((int) ($response->header('Retry-After') ?: 60));
            return;
        }

        if ($response->serverError()) {
            $response->throw(); // 5xx: retried with the backoff above
        }

        $this->fail(new RuntimeException('apiwpp '.$response->status().': '.$response->json('error')));
    }
}

O despacho, onde o pedido sai para entrega:

SendWhatsApp::dispatch(
    connectionId: $store->apiwpp_connection_id,
    to: $order->customer_phone,
    message: "Olá, {$order->customer_name}! Seu pedido {$order->number} saiu para entrega.",
    clientRef: "pedido-{$order->id}-envio",
);

O 429 com new_recipient_cap_reached é o teto de destinatários novos do número em 24 horas, parte da fila com ritmo anti-bloqueio: nada entra na fila, e o release() devolve o Job depois do tempo do Retry-After. Um release() conta como tentativa, então ajuste $tries ao seu volume. Os 4xx restantes (corpo inválido, chave sem escopo, conexão fora do status open) falham de vez, porque repetir não resolve.

Rota de webhook com middleware de assinatura

Com o segredo definido no projeto, cada entrega traz X-Sales-Timestamp e X-Sales-Signature (sha256= seguido do HMAC-SHA256 de timestamp + "." + corpo bruto). O middleware confere as duas coisas antes de o controller existir:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class VerifyApiwppSignature
{
    public function handle(Request $request, Closure $next): Response
    {
        $secret = config('services.apiwpp.webhook_secret');
        if (! is_string($secret) || $secret === '') {
            abort(500, 'APIWPP_WEBHOOK_SECRET is not configured'); // never verify with an empty key
        }

        $timestamp = (string) $request->header('X-Sales-Timestamp', '');
        $signature = (string) $request->header('X-Sales-Signature', '');

        $fresh = ctype_digit($timestamp) && abs(time() - (int) $timestamp) <= 300;
        $expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$request->getContent(), $secret);

        abort_unless($fresh && hash_equals($expected, $signature), 401);

        return $next($request);
    }
}

A rota fica em routes/api.php, que não passa pela verificação de CSRF (no Laravel 11 ou mais recente, o arquivo é criado com php artisan install:api). O endereço final é /api/webhooks/apiwpp, que você cadastra no projeto:

// routes/api.php
use App\Http\Middleware\VerifyApiwppSignature;
use App\Jobs\ProcessApiwppEvent;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::post('/webhooks/apiwpp', function (Request $request) {
    ProcessApiwppEvent::dispatch($request->json()->all());

    return response()->noContent(); // 204 right away
})->middleware(VerifyApiwppSignature::class);

O endereço precisa ser https público e responder direto, sem redirecionamento. Responda 2xx em até 10 segundos; qualquer outra resposta gera novas tentativas.

Processar os eventos na fila, sem duplicar

A entrega é pelo menos uma vez: o mesmo evento pode chegar de novo. A chave de deduplicação é o id da mensagem no WhatsApp: data.messageId em message.delivery (somado ao status, que chega uma vez para sent, delivered e read) e data.raw.key.id em message.incoming. O Cache::add só grava se a chave não existe, o que basta para descartar repetidos:

<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Cache;
use Throwable;

class ProcessApiwppEvent implements ShouldQueue
{
    use Queueable;

    public function __construct(public array $event) {}

    public function handle(): void
    {
        $key = 'apiwpp:event:'.$this->key();
        if (! Cache::add($key, true, now()->addDays(2))) {
            return; // already processed
        }

        try {
            $data = $this->event['data'];
            match ($this->event['type']) {
                'message.incoming' => app(\App\Whatsapp\Inbox::class)->receive($data),
                'message.delivery' => app(\App\Whatsapp\Deliveries::class)->update($data),
                'message.send_failed' => app(\App\Whatsapp\Deliveries::class)->failed($data),
                default => null, // unknown types: ignore
            };
        } catch (Throwable $e) {
            Cache::forget($key); // let the retry process it again
            throw $e;
        }
    }

    private function key(): string
    {
        $data = $this->event['data'] ?? [];

        return match ($this->event['type']) {
            'message.delivery' => ($data['messageId'] ?? '').':'.($data['status'] ?? ''),
            'message.incoming' => $data['raw']['key']['id'] ?? sha1(json_encode($this->event)),
            default => sha1(json_encode($this->event)),
        };
    }
}

Use um cache compartilhado entre os workers (Redis ou banco), não o array nem o file de uma máquina só. Os tipos de evento estão em webhooks assinados, e o porquê da idempotência, no guia sobre mensagens duplicadas.

Testar sem chamar a API

O Http::fake troca a API por uma resposta pronta, e o Http::assertSent confere o que o seu código enviou:

use App\Jobs\SendWhatsApp;
use Illuminate\Support\Facades\Http;

Http::fake(['api.apiwpp.com/*' => Http::response(['jobId' => 'job-1', 'scheduledAt' => 1790251205000, 'position' => 1], 202)]);

SendWhatsApp::dispatchSync('conn-1', '5511988887777', 'Olá!', 'pedido-1-envio');

Http::assertSent(fn ($request) => $request['clientRef'] === 'pedido-1-envio'
    && $request->hasHeader('Authorization'));

Para PHP sem framework, ou para o cliente gerado da especificação OpenAPI, veja a integração com PHP.

Perguntas frequentes

Preciso instalar um pacote para usar a apiwpp no Laravel?

Não. O Http facade já faz tudo o que a integração precisa. Se preferir métodos e modelos tipados, o cliente PHP gerado da especificação OpenAPI 3.1 funciona no Laravel: registre o MessagesApi como singleton num service provider.

Por que usar config() e não env() no código?

Porque, com php artisan config:cache, o Laravel deixa de ler o .env em tempo de execução, e env() fora dos arquivos de configuração devolve null. Um segredo de webhook vazio faria o middleware recusar todas as entregas.

Posso colocar a rota do webhook em routes/web.php?

Pode, desde que tire o caminho da verificação de CSRF, porque a apiwpp não envia o token do formulário. No Laravel 11 ou mais recente, isso é feito com validateCsrfTokens(except: [...]) em bootstrap/app.php. A assinatura continua sendo a proteção da rota.

O que acontece se o worker da fila ficar parado?

Os Jobs de envio esperam na fila do Laravel e saem quando o worker volta, e o clientRef impede duplicatas. Os webhooks continuam sendo respondidos com 204, porque a rota só despacha o Job. Se o endpoint cair, a apiwpp tenta de novo e guarda o registro de cada entrega; as que esgotaram as tentativas podem ser reenviadas depois.

Todos: Integrações →

Envie mensagens com curl ou Guzzle, use o cliente PHP gerado da especificação OpenAPI 3.1 e receba os eventos num script que confere a assinatura HMAC-SHA256 com hash_hmac e hash_equals.

Envie mensagens com o fetch nativo do Node.js, sem dependências, e receba os eventos num endpoint Express que verifica a assinatura HMAC-SHA256 de cada entrega.

Tipos gerados da especificação OpenAPI 3.1 com o openapi-typescript e chamadas pelo openapi-fetch: cada rota, corpo, resposta e evento de webhook tipado, sem código escrito à mão.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.