README

Laravel package for the Meta WhatsApp Business Platform Cloud API, with a first-class webhook implementation and database structures prepared for future chat-style views.

This package is in early development. The current implementation focuses on receiving, validating and storing WhatsApp Business webhooks from Meta.

Features

• Webhook verification endpoint for Meta.
• Signature validation with X-Hub-Signature-256.
• Raw webhook event storage for auditing and replay/debugging.
• Normalized contact, conversation, message and status persistence.
• Configurable routes, middleware, database connection and table names.
• Migration stubs ready to publish into a Laravel application.
• Initial structure for Coexistence scenarios, including inbound messages and echoed/manual app activity when Meta sends it through webhooks.

Requirements

• PHP 8.0 or higher.
• Laravel components 11.x, 12.x or 13.x.
• A Meta app configured for WhatsApp Business Platform webhooks.

Installation

Install the package with Composer:

composer require laravel/whatsapp-business

Publish the configuration file:

php artisan vendor:publish --tag=whatsapp-business-config

Publish and run the migrations:

php artisan vendor:publish --tag=whatsapp-business-migrations
php artisan migrate

Configuration

Add the relevant environment variables to your application:

WHATSAPP_BUSINESS_GRAPH_VERSION=v23.0
WHATSAPP_BUSINESS_ACCESS_TOKEN=
WHATSAPP_BUSINESS_PHONE_NUMBER_ID=
WHATSAPP_BUSINESS_ACCOUNT_ID=
WHATSAPP_BUSINESS_APP_SECRET=

WHATSAPP_BUSINESS_WEBHOOK_ENABLED=true
WHATSAPP_BUSINESS_WEBHOOK_VERIFY_TOKEN=
WHATSAPP_BUSINESS_WEBHOOK_VERIFY_SIGNATURE=true
WHATSAPP_BUSINESS_STORE_WEBHOOK_EVENTS=true

WHATSAPP_BUSINESS_ROUTES_ENABLED=true
WHATSAPP_BUSINESS_ROUTE_PREFIX=whatsapp-business
WHATSAPP_BUSINESS_DB_CONNECTION=

By default, the webhook endpoint is:

GET  /whatsapp-business/webhook
POST /whatsapp-business/webhook

Use the GET URL in Meta's webhook configuration. The package validates hub.mode, hub.verify_token and returns hub.challenge when the verification token matches.

Meta webhook POST requests are accepted only when the request signature matches the configured app secret, unless signature verification is explicitly disabled.

Stored Data

The webhook handler stores the original Meta payload in whatsapp_business_webhook_events. It also extracts data into normalized tables:

• whatsapp_business_contacts
• whatsapp_business_conversations
• whatsapp_business_messages
• whatsapp_business_message_statuses

This keeps the complete event payload available while also making it practical to build a chat view later by querying conversations and ordering messages by occurred_at.

Routes

Routes are enabled by default and use the api middleware group. You can change this in config/whatsapp-business.php:

'route' => [
    'enabled' => true,
    'prefix' => 'whatsapp-business',
    'middleware' => ['api'],
    'name' => 'whatsapp-business.',
],

Development

Install dependencies:

composer install

Useful commands:

composer test
composer analyse
composer format

The package currently has its first implementation layer in place. Tests and higher-level API clients are expected to evolve as the package grows.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Security

If you discover a security vulnerability, please do not open a public issue. Follow the process in SECURITY.md.

License

This package is open source software licensed under the MIT license.