PHPackages                             renzojohnson/whatsapp-webhook - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. renzojohnson/whatsapp-webhook

ActiveLibrary[API Development](/categories/api)

renzojohnson/whatsapp-webhook
=============================

Lightweight WhatsApp Cloud API webhook parser. Typed notifications for messages, statuses, and errors. HMAC signature verification. Zero dependencies.

v0.26.03.16(4mo ago)20MITPHPPHP ^8.4

Since Mar 17Pushed 4mo agoCompare

[ Source](https://github.com/renzojohnson/whatsapp-webhook)[ Packagist](https://packagist.org/packages/renzojohnson/whatsapp-webhook)[ Docs](https://renzojohnson.com)[ RSS](/packages/renzojohnson-whatsapp-webhook/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

WhatsApp Webhook
================

[](#whatsapp-webhook)

[![Latest Version](https://camo.githubusercontent.com/57d8fd8fd7197bd8e648878965e2bd2209f5ff19d49e95311efd9276fd100f00/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f72656e7a6f6a6f686e736f6e2f77686174736170702d776562686f6f6b2e737667)](https://packagist.org/packages/renzojohnson/whatsapp-webhook)[![PHP Version](https://camo.githubusercontent.com/fad168d8fb5bdc95e301d397bde17b364a3cfab6ed313ec9675098285b4c3a70/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f72656e7a6f6a6f686e736f6e2f77686174736170702d776562686f6f6b2e737667)](https://packagist.org/packages/renzojohnson/whatsapp-webhook)[![License](https://camo.githubusercontent.com/13c3838fad5f5381260bfa8ea1be0d577e0ca03c4c6a425661abff0e92d566bf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f72656e7a6f6a6f686e736f6e2f77686174736170702d776562686f6f6b2e737667)](https://github.com/renzojohnson/whatsapp-webhook/blob/main/LICENSE)

Lightweight WhatsApp Cloud API webhook parser. Typed notifications for messages, statuses, and errors. HMAC signature verification. Zero dependencies.

**Author:** [Renzo Johnson](https://renzojohnson.com)

Requirements
------------

[](#requirements)

- **PHP 8.4 or higher** (uses `readonly` classes and enums)
- `ext-json`
- No other extensions or libraries required (zero dependencies)

Installation
------------

[](#installation)

```
composer require renzojohnson/whatsapp-webhook
```

Quick Start
-----------

[](#quick-start)

```
use RenzoJohnson\WhatsAppWebhook\WebhookHandler;
use RenzoJohnson\WhatsAppWebhook\MessageType;
use RenzoJohnson\WhatsAppWebhook\Notification\MessageNotification;

$handler = new WebhookHandler('your-app-secret');

// Register listeners
$handler->onMessage(MessageType::Text, function (MessageNotification $msg): void {
    echo "Message from {$msg->from}: {$msg->text()}";
});

// Verify signature and handle
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';

if (!$handler->verifySignature($rawBody, $signature)) {
    http_response_code(401);
    exit;
}

$handler->handle($rawBody);
http_response_code(200);
```

Webhook Endpoint Setup
----------------------

[](#webhook-endpoint-setup)

```
use RenzoJohnson\WhatsAppWebhook\WebhookHandler;
use RenzoJohnson\WhatsAppWebhook\WebhookException;

$handler = new WebhookHandler('your-app-secret');

// Step 1: Handle Meta's verification challenge (GET)
if ($_SERVER['REQUEST_METHOD'] === 'GET') {
    $challenge = $handler->handleVerification($_GET, 'your-verify-token');

    if ($challenge !== null) {
        echo $challenge;
        exit;
    }

    http_response_code(403);
    exit;
}

// Step 2: Verify signature (POST)
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';

if (!$handler->verifySignature($rawBody, $signature)) {
    http_response_code(401);
    exit;
}

// Step 3: Parse and handle
try {
    $notifications = $handler->handle($rawBody);
    http_response_code(200);
} catch (WebhookException $e) {
    http_response_code(400);
}
```

Message Types
-------------

[](#message-types)

TypeEnumDescription`text``MessageType::Text`Plain text message`image``MessageType::Image`Image with optional caption`video``MessageType::Video`Video with optional caption`audio``MessageType::Audio`Audio message`document``MessageType::Document`Document with filename`sticker``MessageType::Sticker`Sticker`location``MessageType::Location`GPS coordinates with name/address`contacts``MessageType::Contacts`Contact cards`button``MessageType::Button`Quick reply button tap`interactive``MessageType::Interactive`Button reply or list selection`reaction``MessageType::Reaction`Emoji reaction`order``MessageType::Order`Product orderListen by Message Type
----------------------

[](#listen-by-message-type)

```
use RenzoJohnson\WhatsAppWebhook\MessageType;
use RenzoJohnson\WhatsAppWebhook\Notification\MessageNotification;

$handler->onMessage(MessageType::Text, function (MessageNotification $msg): void {
    echo $msg->text();
});

$handler->onMessage(MessageType::Image, function (MessageNotification $msg): void {
    echo "Image: {$msg->mediaId()} ({$msg->mediaMimeType()})";
    echo "Caption: {$msg->caption()}";
});

$handler->onMessage(MessageType::Location, function (MessageNotification $msg): void {
    echo "Location: {$msg->latitude()}, {$msg->longitude()}";
    echo "Name: {$msg->locationName()}";
});

$handler->onMessage(MessageType::Interactive, function (MessageNotification $msg): void {
    if ($msg->interactiveType() === 'button_reply') {
        echo "Button: {$msg->interactiveButtonTitle()} (ID: {$msg->interactiveButtonId()})";
    }
    if ($msg->interactiveType() === 'list_reply') {
        echo "List: {$msg->interactiveListTitle()}";
    }
});

$handler->onMessage(MessageType::Reaction, function (MessageNotification $msg): void {
    echo "Reacted with {$msg->reactionEmoji()} to {$msg->reactionMessageId()}";
});
```

Listen to All Messages
----------------------

[](#listen-to-all-messages)

```
$handler->onAnyMessage(function (MessageNotification $msg): void {
    error_log($msg->getSummary());
});
```

Status Updates
--------------

[](#status-updates)

```
use RenzoJohnson\WhatsAppWebhook\StatusType;
use RenzoJohnson\WhatsAppWebhook\Notification\StatusNotification;

$handler->onStatus(StatusType::Delivered, function (StatusNotification $status): void {
    echo "Delivered to {$status->recipientId}";
});

$handler->onStatus(StatusType::Read, function (StatusNotification $status): void {
    echo "Read by {$status->recipientId}";
});

$handler->onStatus(StatusType::Failed, function (StatusNotification $status): void {
    if ($status->hasErrors()) {
        echo "Error {$status->errorCode()}: {$status->errorTitle()}";
    }
});

$handler->onAnyStatus(function (StatusNotification $status): void {
    error_log($status->getSummary());
});
```

Pricing and Conversation Info
-----------------------------

[](#pricing-and-conversation-info)

```
$handler->onAnyStatus(function (StatusNotification $status): void {
    if ($status->isBillable()) {
        echo "Category: {$status->pricingCategory()}";
        echo "Model: {$status->pricingModel()}";
    }

    if ($status->conversationId()) {
        echo "Conversation: {$status->conversationId()}";
        echo "Origin: {$status->conversationOrigin()}";
    }
});
```

Forwarded Messages
------------------

[](#forwarded-messages)

```
$handler->onAnyMessage(function (MessageNotification $msg): void {
    if ($msg->isForwarded()) {
        echo "This message was forwarded";
    }

    if ($msg->isFrequentlyForwarded()) {
        echo "This message has been forwarded many times";
    }

    if ($msg->contextMessageId()) {
        echo "Reply to: {$msg->contextMessageId()}";
    }
});
```

Parse Without Dispatching
-------------------------

[](#parse-without-dispatching)

```
$notifications = $handler->parse($rawBody);

foreach ($notifications as $notification) {
    if ($notification instanceof MessageNotification) {
        echo $notification->getSummary();
    }
}
```

Error Handling
--------------

[](#error-handling)

```
use RenzoJohnson\WhatsAppWebhook\WebhookException;

try {
    $handler->parse($rawBody);
} catch (WebhookException $e) {
    // Invalid JSON, wrong object type, empty entry
}
```

Related Packages
----------------

[](#related-packages)

- [whatsapp-cloud-api](https://packagist.org/packages/renzojohnson/whatsapp-cloud-api) — Send WhatsApp messages via Cloud API

Links
-----

[](#links)

- [Packagist](https://packagist.org/packages/renzojohnson/whatsapp-webhook)
- [GitHub](https://github.com/renzojohnson/whatsapp-webhook)
- [Issues](https://github.com/renzojohnson/whatsapp-webhook/issues)
- [Author](https://renzojohnson.com)

License
-------

[](#license)

MIT License. Copyright (c) 2026 [Renzo Johnson](https://renzojohnson.com).

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance74

Regular maintenance activity

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

143d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6e1b69733e3d1fd486158d322c23d99281623046b3c357529c9930e50d73fcda?d=identicon)[renzo.johnson](/maintainers/renzo.johnson)

---

Top Contributors

[![renzojohnson](https://avatars.githubusercontent.com/u/4695400?v=4)](https://github.com/renzojohnson "renzojohnson (1 commits)")

---

Tags

phpwebhookwhatsappmetawhatsapp-businesswhatsapp-cloud-apiwhatsapp-webhook

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/renzojohnson-whatsapp-webhook/health.svg)

```
[![Health](https://phpackages.com/badges/renzojohnson-whatsapp-webhook/health.svg)](https://phpackages.com/packages/renzojohnson-whatsapp-webhook)
```

###  Alternatives

[kstmostofa/laravel-whatsapp

Dual-backend Laravel package for WhatsApp: Meta Cloud API + bundled whatsapp-web.js sidecar. Ships a Livewire/Flux admin UI, queued jobs, webhooks with HMAC, Eloquent models, broadcasting, and CLI lifecycle commands.

2041.5k](/packages/kstmostofa-laravel-whatsapp)[stymiee/authnetjson

Library that abstracts Authorize.Net's JSON APIs. This includes the Advanced Integration Method (AIM), Automated Recurring Billing (ARB), Customer Information Manager (CIM), Transaction Reporting, Simple Integration Method (SIM), and Webhooks.

19631.3k](/packages/stymiee-authnetjson)[scriptdevelop/whatsapp-manager

Paquete para manejo de WhatsApp Business API en Laravel

793.9k](/packages/scriptdevelop-whatsapp-manager)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)