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(1mo ago)20MITPHPPHP ^8.4

Since Mar 17Pushed 1mo 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 1mo 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

38

—

LowBetter than 84% of packages

Maintenance95

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

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

53d 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

[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.

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

Paquete para manejo de WhatsApp Business API en Laravel

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

PHPackages © 2026

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